TOOI - URI-strategie en afhankelijkheden 1.0.1

KOOP Standaard
Vastgestelde versie

Deze versie:
https://standaarden.overheid.nl/tooi/doc/def-st-tooi-uri-strategie-20240129
Laatst gepubliceerde versie:
https://standaarden.overheid.nl/tooi/doc/tooi-uri-strategie
Redacteur:
TOOI-beheerteam (KOOP)
Auteur:
Kennis- en Exploitatiecentrum voor Officiële Overheidspublicaties (KOOP)

Status van dit document

Dit is de definitieve versie van dit document. Wijzigingen naar aanleiding van consultaties zijn doorgevoerd.

Samenvatting

Het doel van TOOI is het definiëren van een gemeenschappelijke taal waarmee data en metadata uitgedrukt kunnen worden, zodat overheidsinformatie beter vindbaar, toegankelijk, interoperabel en herbruikbaar wordt. Dit document beschrijft de conventies die gebruikt worden om TOOI-URIs te munten en de relatie met extern gedefinieerde resources.

De familie van TOOI-documenten

Dit document maakt deel uit van de familie van TOOI-documenten die gepubliceerd wordt op standaarden.overheid.nl/tooi.

Documentatie

Dit document is gepubliceerd door KOOP, het Kennis- en exploitatiecentrum voor Officiële Overheidspublicaties. Zie het beheerplan voor nadere informatie.

Feedback is welkom

Indien u vragen heeft, of op- of aanmerkingen wilt maken op dit document, dan vindt u hier hoe u dat publiekelijk of anoniem kunt doen.

Alle commentaar is welkom.

1. URI-strategie en afhankelijkheden

Dit document beschrijft de conventies die gebruikt worden om TOOI-URIs te munten en de relatie met extern gedefinieerde resources.

1.1 Resources en URIs

RDF gebruikt URIs als "woorden" om uitspraken mee te doen. In een RDF-uitspraak verwijzen de URIs naar resources, dat wil zeggen: dingen in de wereld, inclusief ook taalelementen zoals klassen en properties. TOOI is een kennismodel uitgedrukt in RDF. Voor TOOI is de gemeente Haarlem een resource, is de klasse Gemeente zoals gedefinieerd in de TOOI-ontologie een resource, en is ook de relatie "... ligt in de provincie ..." een resource. Deze drie resources worden aangeduid met behulp van URIs, te weten gemeente:gm0392, tooiont:Gemeente, en tooiont:ligtInProvincie.

1.2 Het gebruik van http-URIs

In de context van RDF is het goed gebruik om http-URIs te gebruiken. Alle TOOI-URIs zijn http-URIs, evenals URIs van resources die binnen TOOI gebruikt worden en die buiten TOOI zijn gedefinieerd, zoals rdfs:Class, skos:Concept en dcterms:language. Het grote voordeel van http-URIs is dat de vorm van de URI iets zegt over de partij die de URI heeft gemunt (het domeingedeelte van de URI). Een bijkomende gedachte is dat de munter van de URI informatie over de resource verstrekt wanneer iemand (of iets, zoals een machine) de URI gebruikt als URL in een http GET-request. Anders gezegd: als je de URI intypt in je browser, dan krijg je informatie over de resource terug. Dit is handig, maar er ligt ook verwarring op de loer:

Met inachtneming van deze punten is het nuttig en wenselijk TOOI-URIs niet alleen te munten met de bijbehorende (referentiële) semantiek, maar deze ook dereferenceable te maken. In eerste instantie zijn de TOOI-URIs dit nog niet. Op zeker moment zal een resolver beschikbaar komen.

1.3 Grafen, resources, en het munten van URIs

Een centrale eenheid van informatie in een RDF-kennismodel is de graaf: een verzameling knooppunten (resources) en verbindingen (eveneens resources). Elke combinatie van een knooppunt-verbinding-knooppunt is een uitspraak, ook wel triple genoemd. Grafen kunnen resources delen en daardoor samen ook weer een graaf vormen. De elementaire grafen zijn de kleinste eenheden binnen een kennismodel. Dat zijn de eenheden van beheer en onderhoud. Binnen TOOI zijn dat dus de eerder aangeduide modules.

Elke graaf wordt geïdentificeerd met een URI — ook hier worden http-URIs gebruikt. Semantisch gezien hebben grafen een aparte positie in het RDF-informatiemodel: de relatie tussen een URI en een resource is semantisch gezien een andere dan die tussen de URI van een graaf en de graaf (zie Hoofdstuk 4 van [rdf11-concepts]). Het onderscheid is subtiel en niet belangrijk voor normaal gebruik van TOOI.

De URI van een graaf wordt aangeduid met de termen graphURI, baseURI en (in OWL ook wel) ontology URI. Een RDF-graaf kan geserializeerd worden in diverse formats, zoals Turtle en XML-RDF. De bestandsnaam van een serialisatie is vaak gelijk aan een onderdeel van de graphURI in combinatie met een extentie zoals .ttl of .xml-rdf.

Een resource kan genoemd worden in heel veel grafen. De URI rdf:type komt bijvoorbeeld in vrijwel elke op het web gepubliceerde RDF-graaf voor. De graaf waarin de resource wordt gedefinieerd en de bijbehorende URI wordt gemunt is echter uniek. In geval van rdf:type (uitgeschreven: <http://www.w3.org/1999/02/22-rdf-syntax-ns#type>) is dat de graaf met de graphURI <http://www.w3.org/1999/02/22-rdf-syntax-ns#>, of kortweg rdf:. Dit illustreert meteen een veel gehanteerde conventie om de URI van de resource te relateren aan de URI van de graaf: de graphURI is de "namespace" van de resource-URI. In het geval van deze specifieke graphURI geldt bovendien dat deze (anders dan veel andere graphURIs) dereferenceable is: als je de graphURI intypt in een browser, dan krijg je een TTL-bestand terug (de serialisatie van de graaf). Om de relatie tussen een resource en de graaf waarin de resource gedefinieerd wordt expliciet te maken wordt normaliter de property rdfs:isDefinedBy gebruikt. Het subject is de resource, het object de graaf.

In TOOI worden resource-URIs gemunt conform deze conventies. Bovendien wordt in de definitie van de resources die een klasse of property zijn expliciet de juiste waarde op voor rdfs:isDefinedBy opgenomen. Deze resources worden gedefinieerd in de ontologie. Bij de definitie van andere resources, zoals concepten en organisaties, wordt voor deze property geen waarde opgenomen. Deze aanpak is gebruikelijk.

Zowel bij het vaststellen van graphURIs als bij het munten van resource-URIs worden een aantal conventies toegepast. Daarbij is goed gekeken naar naar de aanbevelingen van GOV.UK (zie [urips]) en ISA (zie [isa_persistent_uris]).

1.4 Overzicht URI's en namespaces

1.4.1 TOOI-graphURIs, TOOI-namespaces en conventies voor local names van resource-URIs

TOOI-URIs zijn te herkennen aan de eigenschap dat ze met https://identifier.overheid.nl/tooi/ beginnen. Bij graphURIs wordt dit gevolgd door een typeaanduiding:

  • def/  — voor ontologieën en thesauri
  • id/  — voor registers
  • set/ — voor waardelijsten

Dit wordt op zijn beurt gevolgd door een binnen het moduletype unieke naam. Voor thesauri wordt deze nog voorafgegaan door thes/.

Voor grafen die resources definiëren en URIs munten geldt dat de graphURI gevolgd door "/" fungeert als de namespace voor deze URIs.

Voor local names van resource-URIs worden diverse conventies gehanteerd, afhankelijk van het type graaf waarin de resource-URI gemunt wordt.

Local names van properties en klassen (gedefinieerd in een ontologie) zijn betekenisvol. Een overkoepelende conventie daarbij is dat een local name met een hoofdletter begint als de URI verwijst naar een klasse. Local names van properties en individuals beginnen met een kleine letter. Betekenisvolle local names worden gemaakt door het label van de klasse of de propety om te zetten naar UpperCamelCase waarbij we leestekens weglaten.

De volgende tabel somt alle TOOI-namespaceprefixen op en benoemt de conventies die gehanteerd worden bij het munten van local names voor resources.

Prefix Namespacebinding (graphURI + "/") type conventies mbt local names
tooiont: https://identifier.overheid.nl/tooi/def/ont/ ontologie Nederlandse termen
tooiwl: https://identifier.overheid.nl/tooi/def/wl/ ontologie idem (Noot: 'wl' staat voor "waardelijst")
tooikern: https://identifier.overheid.nl/tooi/def/thes/kern/ thesaurus Concepten hebben een opake local name (tooikern:c_bdc265d5). Collecties hebben een opake local name (tooikern:skosCollection_0748250c). Conceptschema's hebben een Nederlandse term als local name, gebaseerd op het prefLabel (tooikern:publicatieblad)
tooixtrn: https://identifier.overheid.nl/tooi/def/thes/xtrn/ thesaurus idem
tooitop: https://identifier.overheid.nl/tooi/def/thes/top/ thesaurus idem
tooiwep: https://identifier.overheid.nl/tooi/def/thes/wep/ thesaurus idem
tooibwb: https://identifier.overheid.nl/tooi/def/thes/bwb/ thesaurus idem
col: https://identifier.overheid.nl/tooi/id/col/ register Instanties van tooiont:Overheidsorganisatie hebben een local name gebaseerd op de tooiont:organisatiecode. Zie de (beschrijving van URIs voor registerresources)[../tooi-registers/index.html#het-munten-van-resource-uris-voor-registerresources]. (Noot: COL staat voor Caribisch Openbaar Lichaam)
gemeente: https://identifier.overheid.nl/tooi/id/gemeente/ register idem
ministerie: https://identifier.overheid.nl/tooi/id/ministerie/ register idem
oorg: https://identifier.overheid.nl/tooi/id/oorg/ register idem (Noot: oorg staat voor overige overheidsorganisatie)
provincie: https://identifier.overheid.nl/tooi/id/provincie/ register idem
so: https://identifier.overheid.nl/tooi/id/so/ register idem (Noot: so staat voor samenwerkingsorganisatie)
waterschap: https://identifier.overheid.nl/tooi/id/waterschap/ register idem
zbo: https://identifier.overheid.nl/tooi/id/zbo/ register idem (Noot: zbo staat voor zelfstandig bestuursorgaan)

De lopende tekst van deze documentatie gebruikt het namespaceprefix zonder dubbele punt maar in monospace font om te verwijzen naar de bij het namespaceprefix horende graphURI. Dus gemeente staat voor de graaf met graphURI <https://identifier.overheid.nl/tooi/id/gemeente>, en tooiont staat voor <https://identifier.overheid.nl/tooi/def/ont>.

1.4.2 Resource-URIs voor instanties van sh:PropertyShape

Een speciaal geval wordt gevormd door URIs van propertyshapes. Een propertyshape is een resource die (syntactische) regels stelt aan het gebruik van een property. Binnen de TOOI-Ontologie worden deze gebruikt om properties te beschrijven in de context van een subjectklasse. De URI bestaat uit het prefix tooiont: gevolgd door de local name van de subjectklasse, een verbingsteken, en de local name van de property. Voorbeeld:

  tooiont:Overheidsorganisatie-begindatum

Deze propertyshape geeft een context-gevoelige definitie van het gebruik van de property tooiont:begindatum bij een instantie van tooiont:Overheidsorganisatie, en stelt eisen aan de cardinaliteit.

1.4.3 TOOI-graphURIs die geen namespace definiëren

Er zijn binnen TOOI ook grafen die geen eigen prefix hebben. In deze grafen worden geen URIs gemunt. Dat zijn waardelijsten en geversioneerde afslagen van thesauri en van de ontologie. De volgende tabel toont alleen enkele voorbeelden:

graphURI type Omschrijving
https://identifier.overheid.nl/tooi/def/ont_v1.0 ontologie Geversioneerde afslag van tooiont, met versieaanduiding 1.0
https://identifier.overheid.nl/tooi/def/thes/top_v1.1 thesaurus Geversioneerde afslag van tooitop, met versieaanduiding 1.1
https://identifier.overheid.nl/tooi/set/gemeente_peildatum/2 waardelijst Versie van de waardelijst gemeenten op peildatum, met volgnummer 2
https://identifier.overheid.nl/tooi/set/gemeente_compleet/1 waardelijst Versie van de waardelijst gemeenten compleet, met volgnummer 1
https://identifier.overheid.nl/tooi/set/toplijst/v3 waardelijst Versie van de waardelijst toplijst, met volgnummer 3

1.4.4 Overige vocabulaires gebruikt binnen TOOI

TOOI maakt veel gebruik van vocabulaires die buiten TOOI gedefinieerd zijn. Dit betreft naast de basisvocabulaires RDF, RDFS en OWL een aantal "upper ontologies" (generieke vocabulaires die breed gebruikt worden), een ontologie van de EU en authority tables (referentiedatasets) van de EU.

De volgende tabel somt alle grafen op die resourcedefinities bevatten die binnen TOOI gebruikt worden, met bijbehorende prefix en namespacebinding (indien van toepassing), de naam (met hyperlink) van de betreffende specificatie en een omschrijving. Net als bij TOOI-namespaces en graphURI's staat in lopende tekst het namespaceprefix zonder dubbele punt maar in monospace font voor de bij het namespaceprefix horende graphURI. Dus org: staat voor de namespace <http://www.w3.org/ns/org#>, en org (zonder dubbele punt) staat voor de graphURI <http://www.w3.org/ns/org>.

Noot: de namespacebinding en de graphURI zijn in sommige gevallen identiek, maar vaak ook niet

Prefix Namespacebinding GraphURI Naam (en link naar specificatie) Omschrijving
adms: https://www.w3.org/TR/vocab-adms# http://www.w3.org/ns/adms Asset Description Metadata Schema [vocab-adms] Toepassingsprofiel van DCAT voor het beschrijven van 'semantische assets' zoals ontologieën en referentiegegevens
dcat: http://www.w3.org/ns/dcat# http://www.w3.org/ns/dcat Data Catalog Vocabulary 2 [vocab-dcat-2] Generiek vocabulaire voor het beschrijven van catalogi
dcterms: http://purl.org/dc/terms/ http://purl.org/dc/terms Dublin Core Metadata Terms [DCTERMS] Generiek vocabulaire voor het beschrijven van metadata van publicaties
euvoc: http://publications.europa.eu/ontology/euvoc# http://publications.europa.eu/ontology/euvoc EUVOC Vocabulaire van de EU voor het vastleggen van EU-referentiedatasets
file-type: http://publications.europa.eu/resource/authority/file-type/ http://publications.europa.eu/resource/authority/file-type FILE TYPE EU-referentiedataset met definities van bestandsformats
language: http://publications.europa.eu/resource/authority/language/ http://publications.europa.eu/resource/authority/language LANGUAGE EU-referentiedataset met definities van talen
dataTypeDefinitions: http://publications.europa.eu/ontology/euvoc/dataTypeDefinitions# http://publications.europa.eu/ontology/euvoc/dataTypeDefinitions EU datatype definitions Definities van datatypes die gebruikt worden in EU-referentiedatasets. De resource-URIs van datatypes die in deze graaf zijn gedefinieerd, zijn gemunt in de euvoc: namespace
org: http://www.w3.org/ns/org# http://www.w3.org/ns/org ORG [vocab-org] Generiek vocabulaire voor het beschrijven van organisaties
owl: http://www.w3.org/2002/07/owl# http://www.w3.org/2002/07/owl OWL [owl2-syntax] Aanvullend vocabulaire voor het definiëren van resources
pav: http://purl.org/pav/ http://purl.org/pav PAV [pav] Meer specifiek vocabulaire voor het beschrijven van provenance van digitale informatieobjecten (bouwt voort op PROV)
prov: http://www.w3.org/ns/prov# http://www.w3.org/ns/prov# PROV-O [prov-o] Generiek vocabulaire voor het beschrijven van provenance
rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# http://www.w3.org/1999/02/22-rdf-syntax-ns# RDF [rdf11-concepts] Basisvocabulaire voor het beschrijven van resources
rdfs: http://www.w3.org/2000/01/rdf-schema# http://www.w3.org/2000/01/rdf-schema# RDFS [rdf11-schema] Basisvocabulaire voor het definiëren van resources
sh: http://www.w3.org/ns/shacl# http://www.w3.org/ns/shacl# SHACL [shacl] Vocabulaire voor het vastleggen van regels (onder meer validatieregels)
skos: http://www.w3.org/2004/02/skos/core# http://www.w3.org/2004/02/skos/core SKOS [skos-reference] Vocabulaire voor het beschrijven van concepten
xsd: http://www.w3.org/2001/XMLSchema# nvt XSD [xmlschema-ref] De standaard voor XML-schema's

1.5 Overzicht afhankelijkheden

Een definiërende eigenschap van een kennismodel (knowledge graph) is het gebruik van een graafrepresentatie. Elke combinatie van grafen is zelf ook weer een graaf — een eigenschap die coalescence genoemd wordt. Dit is een verschil met documentrepresentaties zoals in XML: twee XML-documenten vormen niet vanzelfsprekend een samengesteld document. Om deze notie te operationaliseren definieert de RDF-specificatie (in hoofdstuk 4) het begrip RDF Dataset: dat is, gegeven een graaf die beschouwd wordt, de union van die graaf met andere grafen. Bij het werken met een graaf grijpen bijvoorbeeld SPARQL-queries, SHACL-shapes en OWL-inferenties aan op de RDF Dataset.

Het is goed gebruik om in elke graaf waar mogelijk uitsluitend expliciet gedefinieerde resources te noemen. Ongedefinieerde resources dienen vermeden te worden. Anders gezegd: als je een graaf beschouwt moet je van elke genoemde resource ook de definitie van die resource kunnen vinden in de RDF Dataset. Dit geldt ook voor resources die in een andere graaf gedefinieerd zijn. Daar zijn dan twee methoden voor:

  1. Kopieer de definitie van de resource simpelweg in de lokale graaf
  2. Importeer de externe graaf in de lokale graaf met owl:imports. Gebruikers die een eigen omgeving met de lokale graaf willen werken zullen de betreffende grafen beschikbaar moeten maken aan de tooling die ze gebruiken. Veel tools proberen de externe graaf automatisch te downloaden door de graphURI te dereferencen met behulp van een http-request, maar dat lukt alleen als de tool internettoegang heeft en de graphURI inderdaad dereferenceable is. In lang niet alle gevallen wordt aan beide voorwaarden gedaan. In die gevallen zal de gebruiker dit handmatig moeten regelen

De grafen rdf, rdfs en owl (en de datatypedefinities in XSD) hoeven nooit geïmporteerd te worden: deze maken per definitie deel uit van de RDF Dataset. De twee genoemde methoden worden in de praktijk beide gebruikt, en vaak naast elkaar. Te illustratie hier een paar praktijkgevallen.

Een thesaurus zal typisch skos importeren met owl:imports. Je zou ervoor kunnen kiezen in plaats daarvan precies díe resourcedefinities uit SKOS te kopieëren die je in de thesaurus gebruikt. Maar dat worden er waarschijnlijk heel veel. En het is onhandig als je een SKOS-resource wilt gebruiken die je nog niet gekopieerd had. Het naar binnen halen van de hele graaf is de gebruikelijke optie.

De graaf pav gebruikt een aantal resources uit prov. Deze zijn "fysiek" in pav gekopieerd. Daarmee wordt de graaf "self contained" en is deze "upper ontology" eenvoudig bruikbaar. Voorkomen wordt dat gebruikers van pav per definitie ook prov moeten downloaden en beschikbaar maken in de werkomgeving.

Een datagraaf die een paar klassen en properties gebruikt die gedefinieerd zijn in <http://schema.org>, de "upper ontology" die op 1,2 miljard webpagina's gebruikt wordt, kopieert meestal de benodigde definities. De graaf is erg groot, en importeren is daarom praktisch gesproken onhandig

Het volgende schema geeft een indicatie van hoe de TOOI-modules omgaan met imports en het kopieëren van resourcedefinities. De grafen gerepresenteert als zwarte blokken (TOOI-grafen) en de grafen gerepresenteerd als blauwe blokken zijn in de voorgaande paragraaf beschreven.

Toelichting:

TOOI-kennismodel
Figuur 1 Overzicht afhankelijkheden TOOI-kennismodel
  1. SHACL wordt vanaf versie 1.0.6 van tooiont gebruikt om het conceptuele model uit te drukken. Slechts een beperkt aantal OWL-resources wordt nog gebruikt naast SHACL.
  2. In tooiont worden drie typedefinities uit dataTypeDefinitions gekopieerd. Deze worden gebruikt in tooixtrn
  3. Het gemeenteregister gebruikt resources gedefinieerd in provincie als waarde voor de property tooiont:ligtInProvincie
  4. Waardelijsten afgeleid uit het gemeenteregister gebruiken resources gedefinieerd in provincie als waarde voor de property tooiont:ligtInProvincie. Deze worden geïmporteerd via de provinciewaardelijsten
  5. De registers en de registerwaardelijsten importeren tooikern omdat daarin de concepten gedefinieerd zijn die het waardebereik vormen van tooiont:organisatiesoort

A. Referenties

A.1 Informatieve referenties

[DCTERMS]
DCMI Metadata Terms. DCMI Usage Board. DCMI. 20 January 2020. DCMI Recommendation. URL: https://www.dublincore.org/specifications/dublin-core/dcmi-terms/
[isa_persistent_uris]
Study on persistent URIs, with identification of best practices and recommendations on the topic for the MSs and the EC. Phil Archer; Stijn Goedertier; Nikolaos Loutas. ISA. URL: https://joinup.ec.europa.eu/sites/default/files/document/2013-02/D7.1.3%20-%20Study%20on%20persistent%20URIs.pdf
[owl2-syntax]
OWL 2 Web Ontology Language Structural Specification and Functional-Style Syntax (Second Edition). Boris Motik; Peter Patel-Schneider; Bijan Parsia. W3C. 11 December 2012. W3C Recommendation. URL: https://www.w3.org/TR/owl2-syntax/
[pav]
PAV - Provenance, Authoring and Versioning. Paolo Ciccarese; Stian Soiland-Reyes. URL: https://pav-ontology.github.io/pav/
[prov-o]
PROV-O: The PROV Ontology. Timothy Lebo; Satya Sahoo; Deborah McGuinness. W3C. 30 April 2013. W3C Recommendation. URL: https://www.w3.org/TR/prov-o/
[rdf11-concepts]
RDF 1.1 Concepts and Abstract Syntax. Richard Cyganiak; David Wood; Markus Lanthaler. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf11-concepts/
[rdf11-schema]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/rdf-schema/
[shacl]
Shapes Constraint Language (SHACL). Holger Knublauch; Dimitris Kontokostas. W3C. 20 July 2017. W3C Recommendation. URL: https://www.w3.org/TR/shacl/
[skos-reference]
SKOS Simple Knowledge Organization System Reference. Alistair Miles; Sean Bechhofer. W3C. 18 August 2009. W3C Recommendation. URL: https://www.w3.org/TR/skos-reference/
[urips]
URI Patterns. UK Government Linked Data Working Group (UKGovLD). KOOP. URL: http://ukgovld.github.io/ukgovldwg/recommendations/uri-patterns.html
[vocab-adms]
Asset Description Metadata Schema (ADMS). Phil Archer; Gofran Shukair. W3C. 1 August 2013. W3C Working Group Note. URL: https://www.w3.org/TR/vocab-adms/
[vocab-dcat-2]
Data Catalog Vocabulary (DCAT) - Version 2. Riccardo Albertoni; David Browning; Simon Cox; Alejandra Gonzalez Beltran; Andrea Perego; Peter Winstanley. W3C. 4 February 2020. W3C Recommendation. URL: https://www.w3.org/TR/vocab-dcat-2/
[vocab-org]
The Organization Ontology. Dave Reynolds. W3C. 16 January 2014. W3C Recommendation. URL: https://www.w3.org/TR/vocab-org/
[xmlschema-ref]
W3C XML Schema Definition Language (XSD): Component Designators. Mary Holstege; Asir Vedamuthu. W3C. 19 January 2010. W3C Candidate Recommendation. URL: https://www.w3.org/TR/xmlschema-ref/
KOOP Standaard - Vastgestelde versie