Skip to content

Create and integrate a custom vocabulary#

This tutorial will guide you through the process of creating your first custom vocabulary. You will create an example vocabulary for the dct:publisher property based on SKOS, add it to your piveau instance, and make it availabe for enrichment in your search. When you have completed this tutorial, you can use your vocabulary in your metadata as you use the built-in vocabularies.

About Vocabularies

It is currently not possible to extend or change the built-in vocabularies of piveau in a fine-grained way without changing the source code. But the method described in this tutorial is a great way to extend or completely change the built-in vocabualaries by mapping properties to your custom vocabulary.

Prerequisites#

  • Basic knowledge of piveau, RDF and SKOS
  • A running development instance of piveau hub-repo and hub-search (see Quick Start)

Background#

Piveau supports the use and integration of SKOS vocabularies. An extensive selection of commonn vocabularies used in DCAT-AP and derived profiles is already integrated. When you want to add your custom vocabulary you need to create it as a SKOS vocabulary. Your vocabulary will get stored as is in the Triplestore, but only a subset of properties is indexed and made available in Elasticsearch aka the UI. The following properties of a skos:Concept can be currently indexed:

  • dc11:identifier
  • skos:inScheme
  • foaf:homepage
  • skos:prefLabel
  • skos:altLabel
  • The URI of the concept

Step 1 - Example Vocabulary#

First, you create a very simple example vocabulary. The vocabulary is called my-publishers and includes two dummy publishers. Just store it somewhere, e.g. my-publishers.ttl.

@prefix skos:  <http://www.w3.org/2004/02/skos/core#> .
@prefix at:    <http://publications.europa.eu/ontology/authority/> .
@prefix atold: <http://publications.europa.eu/resource/authority/> .
@prefix dc11:  <http://purl.org/dc/elements/1.1/> .
@prefix foaf:  <http://xmlns.com/foaf/0.1/> .

<http://myowndomain.de/vocabularies/my-publishers>
    a              skos:ConceptScheme ;
    skos:prefLabel "My Publishers"@en .

<http://myowndomain.de/vocabularies/my-publishers/publisher-a>
    a               skos:Concept ;
    dc11:identifier "publisher-a" ;
    skos:inScheme   <http://myowndomain.de/vocabularies/my-publishers> ;
    foaf:homepage   <http://myowndomain.de/homepage> ;
    skos:prefLabel  "Publisher A"@en, "Veroeffentlicher A"@de ;
    skos:altLabel   "Pub. A"@en, "Ver. A"@de .

<http://myowndomain.de/vocabularies/my-publishers/publisher-b>
    a               skos:Concept ;
    dc11:identifier "publisher-b" ;
    skos:inScheme   <http://myowndomain.de/vocabularies/my-publishers> ;
    foaf:homepage   <http://myowndomain.de/publisherb> ;
    skos:prefLabel  "Publisher B"@en, "Veroeffentlicher B"@de ;
    skos:altLabel   "Pub. B"@en, "Ver. B"@de .

Now you just send it to hub-repo with a simple PUT request:

curl -i -X PUT -H "X-API-Key: yourRepoApiKey" -H "Content-Type: text/turtle" --data @my-publishers.ttl localhost:8081/vocabularies/my-publisher

You can verify the creation in hub-repo by accessing: http://localhost:8081/vocabularies/my-publisher.ttl. In addition, you can immediately use it with hub-search, e.g. for an auto-completion UI: http://localhost:8084/search?filter=vocabulary&vocabulary=my-publisher&q=A

You will see how an entry of your vocabulary gets indexed:

{
  "result": {
    "pref_label": {
      "de": "Veroeffentlicher A",
      "en": "Publisher A"
    },
    "extensions": {
      "foaf_homepage": "http://myowndomain.de/homepage"
    },
    "id": "publisher-a",
    "in_scheme": "http://myowndomain.de/vocabularies/my-publishers",
    "resource": "http://myowndomain.de/vocabularies/my-publishers/publisher-a",
    "alt_label": {
      "de": "Ver. A",
      "en": "Pub. A"
    }
  }
}

Step 2 - Usage in a Dataset#

A major use case for a vocabulary is to use it in a dataset or other entity for resolving URIs to human-readable a form. Hub-search allows to easily enrich URIs based on a vocabulary. In order to use the new publisher vocabulary for the publisher field, add the following to the configuration of hub-search: 

"vocabulary": {
    "my-publisher": {
        "fields": [
            "publisher"
        ],
        "replacements": [
            "name:pref_label.en",
            "homepage:extensions.foaf_homepage",
            "resource:resource"
        ]
    },
This config basically instructs to map the properties name, homepage, resource of the field publisher with the fields pref_label.en, extensions.foaf_homepage, and resource, respectively. These properties for a publisher are pre-defined in the standard profile of piveau. Out-of-the box you cannot include more properties. If you need more customization have look into piveau profiles.

Now you can just use the URI of your custom publisher in a dataset:

@prefix dcat:   <http://www.w3.org/ns/dcat#> .
@prefix dct:    <http://purl.org/dc/terms/> .

<https://piveau.io/set/data/test-dataset>
    a                      dcat:Dataset ;
    dct:description        "This is an example Dataset"@en ;
    dct:title              "Example Dataset"@en ;
    dct:publisher          <http://myowndomain.de/vocabularies/my-publishers/publisher-b> ;
    dcat:theme             <http://publications.europa.eu/resource/authority/data-theme/ENVI> ;
    dcat:distribution      <https://piveau.io/set/distribution/1> .

<https://piveau.io/set/distribution/1>
    a              dcat:Distribution ;
    dct:format     <http://publications.europa.eu/resource/authority/file-type/CSV> ;
    dcat:accessURL <https://piveau.eu/set/data/test-dataset> .
If you create this dataset and then retrieve it from hub-search you will see the resolved vocabulary:

"publisher": {
    "type": "Agent",
    "resource": "http://myowndomain.de/vocabularies/my-publishers/publisher-b",
    "name": "Publisher B",
    "homepage": "http://myowndomain.de/publisherb"
},

Conclusion#

In this turotial you have learned how to create and integrate a simple custom vocabulary for the dct:publisher property. Btw. you can also use this method to create an additional vocabulary for the built-in ones. The original vocabulary will still work.