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.
TOOI-inleiding. De doelstelling en structuur van TOOI als kennismodel
TOOI-URI-strategie. De URI-strategie voor het munten van TOOI-URIs en de relatie met externe ontologieën
TOOI-ontologie. Beschrijving van tooiont, de ontologie van overheidsinformatie en overheidsorganisaties conform TOOI
TOOI-waardelijstontologie. Beschrijving van tooiwl, de ontologie voor het beschrijven van waardelijsten in termen van specifieke metadata
TOOI-thesauri. Beschrijving van de algemene structuur van TOOI-thesauri, en hun onderhoudscyclus
TOOI-thes-kern. Beschrijving van de thesaurus tooikern (algemene concepten)
TOOI-thes-xtrn. Beschrijving van de thesaurus tooixtrn (formats, talen)
TOOI-thes-top. Beschrijving van de thesaurus tooitop (thema-indeling overheidspublicaties)
TOOI-thes-wep. Beschrijving van de thesaurus tooiwep (wet elektronische publicaties)
TOOI-thes-bwb. Beschrijving van de thesaurus tooibwb (taxonomieën basis wettenbestand)
TOOI-registers. Beschrijving van de structuur van TOOI-registers, en hun onderhoudscyclus
TOOI-waardelijsten. Beschrijving van de TOOI-waardelijsten op hoofdlijnen, inclusief voorbeelden van gebruik
Bovenstaande documenten vormen samen de normatieve specificatie van de TOOI-standaard. De TOOI-standaard wordt beheerd zoals beschreven in het niet-normatieve TOOI-beheerplan.
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:
De URI staat voor de resource, niet voor de informatie die je terugkrijgt als je de URI als URL gebruikt
Er zijn geen standaarden die bepalen of een URI ook zinvol als URL gebruikt kan worden, en zo ja, wat de http-server dan terugstuurt. Dat kan van alles zijn. Niets is ook goed. Bij gebruik als URL geeft rdfs:Class de RDFS-graaf geserialiseerd als Turtle terug, maar skos:Concept resulteert in een documentatiepagina in html.
Sommige resources zijn resources-not-on-the-web (zoals de gemeente Haarlem), maar er bestaan ook webresources. Juist bij deze resources is het van belang de semantiek van de URI en de pragmatiek van de URI-gebruikt-als-URL uit elkaar te houden. De URI <https://zoek.officielebekendmakingen.nl/stb-2023-27> opgevat als resource-URI verwijst naar de authentieke Wet van 21 december 2022, houdende vaststelling van de begrotingsstaat van de Koning (I) voor het jaar 2023, een webresource. Als je deze URI als URL gebruikt, retourneert de webserver een representatie van deze resource. Zie TOOI-ontologie.
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.
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)
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)
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
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
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
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:
Kopieer de definitie van de resource simpelweg in de lokale graaf
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:
Figuur 1Overzicht afhankelijkheden TOOI-kennismodel
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.
In tooiont worden drie typedefinities uit dataTypeDefinitions gekopieerd. Deze worden gebruikt in tooixtrn
Het gemeenteregister gebruikt resources gedefinieerd in provincie als waarde voor de property tooiont:ligtInProvincie
Waardelijsten afgeleid uit het gemeenteregister gebruiken resources gedefinieerd in provincie als waarde voor de property tooiont:ligtInProvincie. Deze worden geïmporteerd via de provinciewaardelijsten
De registers en de registerwaardelijsten importeren tooikern omdat daarin de concepten gedefinieerd zijn die het waardebereik vormen van tooiont:organisatiesoort
