TOOI - Waardelijsten 1.0.4

Elke waardelijst wordt aangeboden in meerdere formats. De RDF-variant van een waardelijst (geserialiseerd als TTL, XML-RDF of JSON-LD) geldt als basisvariant. De inhoud ervan kent dezelfde informatiestructuren als de onderliggende onderdelen van het kennismodel.

Zoals gezegd onderscheidt TOOI verschillende soorten waardelijsten, in verschillende varianten. Elke soort en variant heeft een primair resourcetype.

Afhankelijk van het type waardelijst zijn er verschillende richtlijnen die we hanteren om te bepalen wanneer een nieuwe versie van een waardelijst wordt gegenereerd en gepubliceerd. Een indicatie hiervan is opgenomen in de volgende tabel.

Op aanvraag van afnemers kunnen er nieuwe versies worden gepubliceerd om bijzondere redenen, bijvoorbeeld een ministeriewaardelijst met een peildatum in het verleden. Hoewel dit niet vaak zal voorkomen, houden we in de systematiek rekening met dergelijke situaties. Oplopende versienummers (volgnummers) van een waardelijst kunnen de hieronder beschreven systematiek dus doorkruisen. De metadata van de waardelijst beschrijft de inhoud van de waardelijst, uit het versienummer valt in principe niets af te leiden.

Doorgaans geldt bij registerwaardelijsten dat een nieuwe versie van zowel de peildatumvariant als de compleetvariant tegelijk wordt gepubliceerd. In de volgende tabel worden deze dus niet apart behandeld.

Een registerwaardelijst bevat uitspraken over organisaties. Welke uitspraken dat precies zijn is deels hetzelfde voor alle organisaties, maar hangt ook af van de organisatiesoort. Een waardelijst over gemeenten zal per gemeente een uitspraak bevatten die vaststelt in welke provincie de gemeente ligt: dat is specifiek voor instanties van de klasse tooiont:Gemeente. Registerwaardelijsten compleet bevatten naast uitspraken over organisaties ook informatie over historie: wanneer is een organisatie opgericht en weer opgeheven, en in welke toestanden is de organisatie geweest. In de XML-varianten ontbreekt een deel van de historische informatie, zie verderop. In TOOI - Ontologie wordt in detail beschreven welke eigenschappen van toepassing zijn bij welke organisatieklasse, en hoe historische informatie gestructureerd is.

Een conceptwaardelijst bevat uitspraken over concepten. Dit betreft voornamelijk prefLabels en andere labels, en eventueel definities en andere zaken. Sommige conceptwaardelijsten bevatten een concepthiërarchie. Deze boomstructuren worden beschreven met behulp van skos:broader. De uitspraak <a> skos:broader <b> betekent dat concept <a> onder concept <b> geordend is. In [skos-reference] wordt dit alles in detail beschreven.

Concepten en concepthiërarchieën worden door KOOP onderhouden in een thesaurusbeheersysteem. De thesauri worden gebruikt om waardelijsten uit te genereren. De thesauri zelf zijn ook beschikbaar. Een schemagebaseerde conceptwaardelijst is feitelijk een deelverzameling van de uitspraken in de thesaurus. Bij een collectiegebaseerde waardelijst is de relatie complexer.

Voor schemagebaseerde waardelijsten geldt dat de inhoud van de waardelijst geselecteerd wordt op basis van een conceptschema. Simpel gesteld bevat de waardelijst informatie over alle concepten die tot het conceptschema behoren.

Collectiegebaseerde conceptwaardelijsten worden geselecteerd op basis van een collectie. Ze hebben daarom een aantal specifieke kenmerken:

• Sommige concepten zijn een instantie van tooiont:Groeperingsconcept. Deze concepten mogen niet gebruikt worden in metadata. Ze kunnen gebruikt worden om bijvoorbeeld de gebruikersinterface van een publicatieplatform vorm te geven.
• Hiërarchische relaties tussen concepten kunnen anders zijn dan in de bronthesaurus
• Een concept kan een prefLabel hebben dat afwijkt van het prefLabel in de bronthesaurus

Zie volgende paragraaf voor nadere toelichting.

  SELECT COUNT(?s)
  WHERE {
      ?s a tooiont:Ministerie .
      FILTER NOT EXISTS {?s a tooiont:HistorischeVersie}
  }

Deze query retourneert het aantal ministerie-objecten, inclusief ministeries die ooit bestaan hebben maar inmiddels zijn opgeheven. Niet meegeteld worden de historische versies van een ministerie. Bij weglating van het filter zullen ook deze meegeteld worden. Dat is bij deze specifieke informatievraag niet de bedoeling.

  SELECT ?oc ?org ?t ?hv
  WHERE {
      [] a tooiont:Toestandswijziging ;
          prov:used / tooiont:afkorting ?org ;
          prov:used / tooiont:organisatiecode ?oc ;
          tooiont:tijdstipWijziging ?t ;
          prov:invalidated / tooiont:afkorting ?hv .
  } ORDER BY ?org

Deze query selecteert alle toestandswijzigingen, en bij elk van deze de huidige (of laatst bekende) afgekorte naam en de organisatiecode van organisatie waar de toestandsverandering betrekking op heeft (prov:used), het tijdstip van wijziging, en de afgekorte naam die hoort bij de toestand die na de wijziging niet meer van kracht was (prov:invalidated). Het resultaat van deze query is (gegeven de (versie van de) genoemde waardelijst):

Dit moet gelezen worden als: er was een samenvoeging op 14 oktober 2010, en als gevolg daarvan zijn VROM en VW (Verkeer en Waterstaat) opgeheven, en is IenW gestart. Merk op dat hierbij de afkortingen gebruikt worden die nu nog geldig zijn, of geldig waren op het moment van opheffen. Voor IenW geldt bijvoorbeeld dat op het moment van oprichting nog MinIenM heette.

Het kan nuttig zijn om organisaties die op een peildatum bestonden uit te vragen, met de naam die op die datum geldig waren. In dit specifieke voorbeeld is het nodig bij elk relevant ministerie de historische versies te vinden (voor zover aanwezig), en daaruit de versie te selecteren die op de peildatum geldig was. Bij het selecteren van de ministeries die bestonden op de peildatum moeten we rekening houden met het feit dat de properties prov:generatedAtTime en prov:invalidatedAtTime voor een gegeven ministerie in voorkomende gevallen ongespcificeerd kunnen zijn. De waarde van prov:generatedAtTime (?gt) kan eenvoudig onbekend zijn. Als de waarde van prov:invalidatedAt (?it) niet is gespecificeerd, dan betekent dat dat het ministerie nog bestaat. Er zijn dus vier mogelijkheden. Om de zaak te vereenvoudigen definiëren we twee variabelen, ?start en ?end, die we gelijk stellen aan ?gt en ?it als deze gespecificeerd zijn. Zo niet, dan geven we ze een waarde in het verre verleden of de verre toekomst (regel 9 en 10). Vervolgens filteren we alle ministeries weg die op de peildatum nog niet of niet meer bestonden (regel 11 en 12).

Wat volgt is een geneste query van twee niveaus diep om de historische versies te vinden en daaruit de juiste te selecteren. 

  SELECT ?org ?naamGeldigOpPeildatum
  WHERE {
      BIND ( ("2010-09-02T00:00:00"^^xsd:dateTime) AS ?peildatum ) .
      ?org a tooiont:Ministerie ;
              rdfs:label ?label .
      FILTER NOT EXISTS { ?org a tooiont:HistorischeVersie }
      OPTIONAL { ?org prov:generatedAtTime ?gt }
      OPTIONAL { ?org prov:invalidatedAtTime ?it }
      BIND ( (IF (bound(?gt), ?gt, "1800-01-01T00:00:00"^^xsd:dateTime)) AS ?start )
      BIND ( (IF (bound(?it), ?it, "2100-01-01T00:00:00"^^xsd:dateTime)) AS ?end )
      FILTER (?start < ?peildatum )
      FILTER (?end > ?peildatum )

      OPTIONAL { 
          SELECT ?org ?naam
          WHERE {
              {
                  SELECT ?org ( MIN( ?eindeGeldigheidVanToestand  )  AS ?e )
                  WHERE {
                      BIND ( ("2010-09-02T00:00:00"^^xsd:dateTime) AS ?peildatum ) .
                      ?tw a tooiont:Toestandswijziging ;
                          prov:used ?org ;
                          tooiont:tijdstipWijziging ?eindeGeldigheidVanToestand ;
                      .
                      FILTER (?eindeGeldigheidVanToestand > ?peildatum)
                  } GROUP BY ?org HAVING BOUND(?org)  ## Filter met HAVING nodig wegens RDF4J-bug
              }
              ?tw2 a tooiont:Toestandswijziging .
              ?tw2 prov:used ?org .
              ?tw2 tooiont:tijdstipWijziging ?e .
              ?tw2 prov:invalidated / rdfs:label ?naam .
          }
      }
      BIND ( (IF (bound(?naam), ?naam, ?label)) AS ?naamGeldigOpPeildatum )
  } 

Het resultaat van deze query is als volgt:

Het doel van de OPTIONAL-groep is om een eventuele historische versie van een ministerie die geldig was op de peildatum te vinden. Zo ja, dan wordt de naam van die historische versie in het resultaat verwerkt. Zo niet, dan nemen we de naam van het ministerie die op het moment van uitvoering van de querie geldig is. Dat gebeurt op regel 34.

We bekijken nu een vereenvoudigde versie van de diepst geneste query. Deze vind per ministerie de bijbehorende toestandswijzigingen en het tijdstip van wijziging:

  SELECT ?org ?tw ?eindeGeldigheidVanToestand 
  WHERE {
      ?tw a tooiont:Toestandswijziging ;
          prov:used ?org ;
          tooiont:tijdstipWijziging ?eindeGeldigheidVanToestand ;
      .
  } 

Dit levert de volgende resultaten op:

We nesten deze query om per ministerie alleen de oudst geregistreerde toestandswijziging te vinden.

  SELECT ?org ?e ?tw2 ?naam
  WHERE {
      {
          SELECT ?org ( MIN( ?eindeGeldigheidVanToestand  )  AS ?e )
          WHERE {
              ?tw a tooiont:Toestandswijziging ;
                  prov:used ?org ;
                  tooiont:tijdstipWijziging ?eindeGeldigheidVanToestand ;
              .
          } GROUP BY ?org HAVING BOUND(?org)  ## Filter met HAVING nodig wegens RDF4J-bug
      }
      ?tw2 prov:used ?org ;
          tooiont:tijdstipWijziging ?e ;
          prov:invalidated / rdfs:label ?naam ;
      .
  }

Deze geeft de volgende resultaten:

De binnenste query geeft de eerste twee kolommen van deze tabel. De resultaatset wordt gejoind met de resultaten van de buitenste query. Daarmee worden de laatste twee kolomen gevonden. Met een paar kleine aanpassingen kunnen we dit in de hoofdquery plakken, binnen de OPTIONAL-groep. In de binnenste query voegen we een filter op peildatum toe. Daartoe moeten we de peildatum nog een keer toekennen: SPARQL query-evaluatie werkt van binnen naar buiten. Buiten de OPTIONAL-groep, op regel 34, wordt getest of er voor het betreffende ministerie een historische naam is gevonden. Die kennen we dan toe aan het resultaat. Zo niet, dan gebruiken we de naam van het ministerie.

Wanneer we ervoor zouden kiezen bij de de historische versie-objecten een startmoment en eindmoment toe te voegen, dan zou de hoofdquery aanzienlijk eenvoudiger zijn. De OPTIONAL-groep ziet er dan als volgt uit:

  OPTIONAL { 
      ?tw a tooiont:Toestandswijziging .
      ?tw prov:used ?org .
      ?tw prov:invalidated / prov:invalidatedAtTime ?e .
      ?tw prov:invalidated / prov:generatedAtTime ?b .
      ?tw prov:invalidated / rdfs:label ?naam .
      FILTER (?b < ?peildatum)
      FILTER (?e > ?peildatum)
  }

Het voordeel van eenvoudig te begrijpen queries gaat echter ten koste van de eenvoud van de data. Het opslaan van veel redundante gegevens maakt data-entry foutgevoelig. Een klein foutje bij de bron of in de verwerkende software kan moeilijk te vinden en lastig te repareren problemen in de data opleveren. We hebben daarom gekozen voor eenvoud in de data.

De waardelijstontologie van TOOI kent vier soorten waardelijsten. Het type waardelijst wordt vastgelegd in de waardelijst zelf, als waarde van rdf:type 

De algemene structuur van XML-waardelijsten in TOOI is zo generiek mogelijk opgezet. De tooi-waardelijst.xsd wordt voor alle soorten waardelijsten gebruikt; maar per soort waardelijst worden bepaalde delen van het schema niet of anders ingezet.

Onderstaande documentatie geeft na een generieke beschrijving voor alle waardelijsten eerst hoe deze vier soorten in de XML-vocabulaire worden uitgedrukt. Daarna volgt de referentiedocumentatie per XML-element.

Elementnamen staan tussen punthaken in een niet-proportioneel (monospaced) lettertype: <element>.

De voorbeelden in deze documentatie zijn zo kort mogelijk. Inhoud die niet relevant is voor het desbetreffende voorbeeld wordt weergegeven met drie puntjes (...).

Complete voorbeelden zijn te vinden onder TOOI/waardelijsten.

Existentiële wijzigingen worden met een vereenvoudigde representatie gecodeerd. Dat betekent dat de XML-variant van de compleetlijsten minder informatie bevat dan de RDF-varianten. De vereenvoudiging is dat de wijzigingsobjecten niet meegenomen worden in de XML. Alleen de opvolgingsrelatie zijn expliciet opgenomen, redundant in twee richtingen: bij de opgeheven organisatie staat een verwijzing naar de opvolger, bij de opvolger naar de voorganger. Hiervoor worden XML-specifieke predicaten gebruikt die niet in het kennismodel gedefinieerd zijn. Deze predicaten zijn niet opgenomen in het kennismodel, omdat dat ze daar redundant zouden zijn en daarom op gespannen voet staan met de doelstelling van interoperabiliteit. Het gaat om de volgende predicaten:

• https://identifier.overheid.nl/tooi/opvolgerVan, het XML-specifieke predicaat dat aangeeft dat het object een voorganger is van de organisatie die het subject is
• https://identifier.overheid.nl/tooi/opgevolgdDoor, het XML-specifieke predicaat dat aangeeft dat het object de opvolger is van de organisatie die het subject is

Deze vereenvoudiging heeft consequenties:

• Omdat een opvolger meerdere voorgangers kan hebben kunnen er meer dan één <uitspraak>-elementen met dit <predicaat> aan een <waarde>  worden gekoppeld.
• Het omgekeerde, een voorganger met meerdere opvolgers (zoals bij op- en afsplitsingen optreedt) , wordt niet in de XML opgenomen. Zie hieronder onder "Missende informatie".
• De <uitspraak> -elementen die betrekking hebben op opvolgingsrelaties worden altijd opgenomen als gegeven van de meest recente organisatie, dus zonder einddatum. Dit correspondeert met het feit dat in het onderliggende semantisch model deze relaties betrekking hebben op organisaties, niet zijnde historische versies. Een <waarde> verwijst wel met tooioint:opvolgerVan  naar al zijn <versie> -elementen, maar niet andersom.

Het voorbeeld hieronder geeft een existentiële wijziging waarin drie imaginaire gemeentes zijn betrokken.

<?xml version="1.0" encoding="UTF-8"?>
<waardelijst xmlns="https://standaarden.overheid.nl/tooi/xmlwaardelijst/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="https://standaarden.overheid.nl/tooi/xmlwaardelijst/
  https://standaarden.overheid.nl/tooi/xmlwaardelijst/3.2.0/tooi-waardelijst.xsd">
  <naam>voorbeeld compleetlijst met existentiële wijzigingen</naam>
  <metadata>
    <uitspraak>
      <predicaat>http://purl.org/dc/terms/identifier</predicaat>
      <object>https://identifier.overheid.nl/tooi/set/ministeries_compleet_existentieel/v1.xml</object>
    </uitspraak>
    <uitspraak>
      <predicaat>http://www.w3.org/1999/02/22-rdf-syntax-ns#type</predicaat>
      <object>https://identifier.overheid.nl/tooi/def/wl/RegisterwaardelijstCompleet</object>
    </uitspraak>
  </metadata>
  <!-- gemeente A, opgeheven -->
  <waarde>
    <code>https://identifier.overheid.nl/tooi/id/gemeente/gm9091</code>
    <label>gemeente Waaibergen</label>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/officieleNaamInclSoort</predicaat>
      <object>gemeente Waaibergen</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/einddatum</predicaat>
      <object>2017-12-31</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/opgevolgdDoor</predicaat>
      <object>https://identifier.overheid.nl/tooi/id/gemeente/gm9093</object>
    </uitspraak>
  </waarde>
  <!-- gemeente B, opgeheven -->
  <waarde>
    <code>https://identifier.overheid.nl/tooi/id/gemeente/gm9092</code>
    <label>gemeente Windhoek</label>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/officieleNaamInclSoort</predicaat>
      <object>gemeente Windhoek</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/einddatum</predicaat>
      <object>2017-12-31</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/opgevolgdDoor</predicaat>
      <object>https://identifier.overheid.nl/tooi/id/gemeente/gm9093</object>
    </uitspraak>
  </waarde>
  <!-- gemeente C, opvolger van A en B -->
  <waarde>
    <code>https://identifier.overheid.nl/tooi/id/gemeente/gm9093</code>
    <label>gemeente Stormbeek</label>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/officieleNaamInclSoort</predicaat>
      <object>gemeente Stormbeek</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/begindatum</predicaat>
      <object>2018-01-01</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/opvolgerVan</predicaat>
      <object>https://identifier.overheid.nl/tooi/id/gemeente/gm9091</object>
    </uitspraak>
    <uitspraak>
      <predicaat>https://identifier.overheid.nl/tooi/opvolgerVan</predicaat>
      <object>https://identifier.overheid.nl/tooi/id/gemeente/gm9092</object>
    </uitspraak>
  </waarde>
</waardelijst>

De volgende informatie is wel in de waardellijstontologie opgenomen, daarmee ook in de andere drie serialisatieformaten, maar niet in deze XML-versie beschikbaar:

• tooiont:tijdstipWijziging: het tijdstip dat de wijziging van kracht is geworden. De gebruiker kan dit afleiden uit de einddatum van de voorganger en de begindatum van de opvolger
• tooiont:grondslag: het wijzigingsbesluit. Als deze informatie nodig is, zal deze erbij gezocht moeten worden
• De soort wijziging (tooiont:Samenvoeging, tooiont:Uitbreiding, etc)
• prov:used-relaties: deze relaties kunnen voorkomen bij gemeentelijke herindeling. Bij bijvoorbeeld een afsplitsing kun je daardoor weten dat gemeente A afgesplitst is van organisatie B. In dat geval is organisatie B geen voorganger maar wel betrokken. Er is dus geen opvolgingsrelatie, en de relatie wordt niet meegenomen in de XML.

Definitie

Het root-element van de XML-waardelijst

Diagram

Kinderen

tooiwl:collectie, tooiwl:metadata, tooiwl:naam, tooiwl:waarde

Definitie

De naam van de waardelijst

Diagram

Type

xs:string

Details

Dit element wordt gevuld met de waarde van tooiont:titel  van de waardelijst in TOOI

Gebruikt door

tooiwl:waardelijst

Definitie

De metadata van de waardelijst zelf

Diagram

Gebruikt door

tooiwl:waardelijst

Kinderen

tooiwl:uitspraak

Definitie

De gegevens van de resource, beschreven als predicaat met een object

Diagram

Gebruikt door

tooiwl:metadata, tooiwl:versie, tooiwl:waarde

Kinderen

tooiwl:object, tooiwl:predicaat

Definitie

Het predicaat van de uitspraak

Diagram

Type

tooiwl:tooi-uri

Gebruikt door

tooiwl:uitspraak

Definitie

Het object van het predicaat van de uitspraak

Diagram

Type

xs:string

Gebruikt door

tooiwl:uitspraak

Definitie

De serialisatie van een concept of registerwaarde uit TOOI

Diagram

Gebruikt door

tooiwl:collectie, tooiwl:waarde, tooiwl:waardelijst

Kinderen

tooiwl:code, tooiwl:label, tooiwl:uitspraak, tooiwl:versie, tooiwl:waarde

Definitie

de TOOI-URI van de waarde

Diagram

Type

tooiwl:tooi-uri

Gebruikt door

tooiwl:waarde

Definitie

De serialisatie van rdf:label

Diagram

Type

xs:string

Gebruikt door

tooiwl:collectie, tooiwl:versie, tooiwl:waarde

Definitie

serialisatie van een historische versie van een organisatie

Diagram

Gebruikt door

tooiwl:waarde

Kinderen

tooiwl:label, tooiwl:uitspraak, tooiwl:versiecode

Definitie

De TOOI-URI van de historische versie

Diagram

Type

tooiwl:tooi-uri

Gebruikt door

tooiwl:versie

Definitie

De serialisatie van een skos:Collection in een collectiegebaseerde waardelijst

Diagram

Gebruikt door

tooiwl:collectie, tooiwl:waardelijst

Kinderen

tooiwl:collectie, tooiwl:collectiecode, tooiwl:expandeert, tooiwl:label, tooiwl:waarde

Definitie

De TOOI-URI van de skos:Collection

Diagram

Type

tooiwl:tooi-uri

Gebruikt door

tooiwl:collectie

Definitie

Het concept waarmee de collectie correspondeert

Diagram

Type

tooiwl:tooi-uri

Gebruikt door

tooiwl:collectie

Definitie

Datatype voor TOOI-URIs

Diagram

Type

xs:anyURI

Gebruikt door

tooiwl:code, tooiwl:collectiecode, tooiwl:expandeert, tooiwl:predicaat, tooiwl:versiecode