Identificatie van tekstelementen

Principe

Elk tekstelement uit de STOP tekstmodellen heeft een eigen identificatie. Die bestaat altijd uit twee identifiers, in navolging van de Akoma Ntoso naamgevingsconventie zoals overgenomen in STOP:

  • een eId (expression identifier) die gerelateerd is aan de positie van het element binnen de tekst.

  • een wId (work identifier) die afgeleid wordt van de initiële eId maar die nooit verandert.

De identifiers dienen ieder een eigen doel.

eId

De eId is bedoeld om een verwijzing te kunnen maken naar een positie in de tekst vanuit een andere tekst. Een eId bestaat uit twee delen: een lokale_id die gebaseerd is op het type tekstelement en het nummer daarvan (bijvoorbeeld art_1 voor artikel 1), en een prefix die gelijk is aan de eId van het container-tekstelement waarin het tekstelement bevat is (bijvoorbeeld van de paragraaf waar het artikel in voorkomt). Dat is om een aantal redenen gedaan.

  1. Als vanuit een juridische tekst naar "het vijfde artikel" in een andere tekst verwezen wordt, dan moet de verwijzing ook bij artikel 5. uitkomen. Het is dan niet van belang of dat hetzelfde artikel is waarnaar bij het opschrijven van de verwijzing verwezen is. Dus als een verwijziging naar "het vijfde artikel" opgeschreven wordt, en er komt in de andere tekst later een nieuw artikel 5 en het oude artikel 5 wordt hernummerd naar artikel 6, dan moet de verwijzing nog steeds bij artikel 5 uitkomen.

  2. Een geoefend mens kan aan de eId in een verwijzing aflezen waar in de tekst de verwijzing uit moet komen. Een verwijzing naar een eId is daarom nog steeds bruikbaar, ook al zouden in de weergave van de tekst de eId van de tekstelementen niet zichtbaar zijn, of als de weergevende software verwijzingen met eId niet ondersteunt.

  3. In juridische teksten komen vaak verwijzingen voor naar teksten van hogere wet- en regelgeving. Die kan in de loop van de tijd veranderen, waarbij niet meteen alle teksten bijgewerkt zullen zijn die ernaar verwijzen. De AKN specificaties voor een eId zijn zo opgesteld dat de verwijzing in dat geval vaak alsnog op de juiste plaats in de tekst kan uitkomen. Als de software die de tekst weergeeft waarnaar verwezen wordt het element met de eId niet meer kan vinden, dan kan in plaats daarvan de prefix van de eId gebruikt worden. De verwijzing komt dan niet exact op de juiste plaats uit, maar waarschijnlijk wel in de buurt.

Om deze redenen is de eId gerelateerd aan de plaats van het tekstelement in de tekst, en is het geen onveranderlijke eigenschap van het element. Zeker na structuurwijzigingen moet de eId van een tekstelement voor elke volgende versie van de tekst opnieuw gegenereerd worden.

wId

De wId is bedoeld om een verwijzing te kunnen maken naar de tekst waarin een bepaalde inhoud te vinden is, bijvoorbeeld een specifiek voorschrift of beleidsregel. De wId wordt daarom gebruikt in annotaties om een duiding of interpretatie van de inhoud van de tekst te kunnen relateren aan de tekst. Aan de wId worden de eisen gesteld:

  • Dezelfde inhoud moet via de wId zijn terug te vinden in alle versies van de tekst.

  • De tekst in het tekstelement mag in verschillende versies anders zijn; dit wordt gezien als een evolutie van dezelfde inhoud (voorschrift, beleidsregel) in de tijd.

  • Pas als de inhoud van een tekstelement in een volgende versie echt niet meer overeenkomt (zoals: het voorschrift gaat over iets totaal anders) krijgt een tekstelement een ander wId.

  • Als een bepaalde versie van de tekst geen element met dat wId heeft, dan is de inhoud waarnaar verwezen wordt niet aanwezig in die versie.

Het is daarom belangrijk dat de wId uniek is over alle versies van de tekst heen. Om dat te garanderen schrijft STOP het gebruik van een versie-specifieke prefix voor bij introductie van nieuwe elementen.

Om een wId gelijk te houden in volgende versies van de tekst moet de ondersteunende software bijhouden hoe de verschillende tekstfragmenten door de schrijver worden verplaatst en hergebruikt, en wanneer de inhoud zodanig verandert dat een nieuwe wId nodig is. Dat is geen eenvoudige functionaliteit. Daarom stelt STOP het gelijk houden van de wId alleen verplicht voor structuur- en inhoudelementen en regeltekst. Als software niet in staat is om voor de andere elementen, zoals inline- of aantekening-elementen, de wId over versies heen constant te houden, dan mag de wId uitsluitend voor die elementen elke versie opnieuw toegekend worden.

Componenten

De regels voor eId en wId gelden binnen een AKN component. Conform AKN is de hoofdtekst van een regeling, besluit etc. een component. In sommige gevallen komen binnen de hoofdtekst onderdelen voor die in STOP als afzonderlijke component gezien worden. De tekst in die component wordt niet gezien als onderdeel van de hoofdtekst-component. De regels voor eId en wId (zoals uniciteit) gelden dan alleen binnen de hoofdtekst-zonder-componenten en afzonderlijk binnen elk van de componenten.

Het is mogelijk te verwijzen naar tekst in een component; dat is elders beschreven.

Elementen met vaste eId en wId

Een aantal elementen heeft een vaste, onveranderlijke eId en een daaraan identieke wId zodat naar deze elementen verwezen kan worden zonder de verdere details van de tekst te kennen:

elementeneId = wId
Aanhefformula_1
AlgemeneToelichtinggenrecital
ArtikelgewijzeToelichtingartrecital
Lichaambody
Motiveringacc
RegelingOpschriftlongTitle
Sluitingformula_2 of formula_2_inst
Toelichtingrecital

NB Indien het element Sluiting meer dan ééns voorkomt (in de hoofdtekst of in een component) dan wordt een "_instX" aan de waarde van zowel de eId als de wId toegevoegd als: "_inst" waarbij volgnummer begint bij 2.

Voor de overige elementen is de eId afgeleid van de positie van het element binnen de tekst van een component. De eId wordt dan als volgt samengesteld:

eId = ([prefix]__)[element_ref](_[nummer])

Hierbij geldt:

onderdeelbetekenis
[prefix]de prefix bevat de eId van het hoger liggende XML-element in de tekststructuur. Als het hoger liggende XML element het tekst:Lichaam is, dan wordt de prefix met de daarop volgende dubbele underscore (__) weggelaten.
[element_ref]Een afkorting van de naam van het xml-element, zoals voorgeschreven door de standaard. Zie onderstaande tabel.
[nummer]Een volgnummer voor het element, moet waar mogelijk afgeleid worden van het nummer van het element dat in de tekst voorkomt. Zie toelichting onder de tabel.

[nummer]

  • Voor een expliciet genummerd element wordt het nummer van het element (uit de tekst) als volgt overgenomen:

    • Spaties in het nummer worden weggelaten.

    • Cijfers, letters, "-" en "." worden overgenomen.

    • Andere tekens worden vervangen door ".".

    • Als de voorgaande voorschriften leiden tot 1 of meerdere punten aan het eind van de eId, dan worden deze weggelaten.

  • Als de voorgaande voorschriften niet leiden tot een unieke eId, dan wordt aan het eind van de eId _inst[volgnummer] toegevoegd, waarbij volgnummer begint bij 2.

  • Voor een element dat niet expliciet genummerd is, wordt het nummer: o_[volgnummer], waarbij volgnummer begint bij 1.

Samenstellen van een wId

Voor de elementen die geen vast wId hebben wordt de wId als volgt samengesteld:

wId = [bevoegd_gezag]_[versienummer]__[eId]

Hierbij geldt:

onderdeelbetekenis
[bevoegd_gezag]De identificatie van het bevoegd gezag dat het tekstelement introduceert. Dit is dezelfde identificatie voor overheden als ook in de naamgeving van documenten gebruikt wordt.
[versienummer]

Een door het bevoegd gezag aan de regelingversie toegekend versienummer, waar het element voor het eerst in verschijnt. Zie versienummer voor een toelichting.

Als dit versienummer gebruikt wordt en het komt terug in de expression identificatie van de regelingversie, dan moet het versienummer in de wId gelijk zijn aan dat in de expression identificatie.

Een alternatief voor versienummer is een compacte weergave van de datum waarop de versie is ontstaan, bijvoorbeeld 2018-11-29

De eisen aan het versienummer in STOP laten ruimte om een UUID als versienummer te gebruiken en de cijfers en letters daarvan in de prefix van de wId te gebruiken.

[eId]Het eId van het element in de versie van de tekst waar het element voor het eerst in verschijnt.

wId versienummer

In software waarmee teksten volgens een STOP model geschreven worden kan het nodig zijn om direct na toevoeging van een nieuw tekstelement de eId en wId te kunnen bepalen zonder dat al bekend is in welke versie van de regeling deze tekst opgenomen zal worden. De eId hangt af van de positie in de tekst waar het element wordt toegevoegd, deze kan dus altijd vastgesteld worden. Om de wId te bepalen moet daar een prefix met versienummer aan worden toegevoegd. Als het versienummer nog onbekend is kan in plaats van het versienummer de datum of de letters en cijfers van een UUID gebruikt worden. Net als bij een 'gewoon' versienummer moet ook bij deze versienummers de wId tussen de regelingversies constant blijven zolang de strekking van de inhoud van betreffende tekst niet wijzigt.

Voorbeelden eId / wId

nrBeschrijvingeIdwId
1Artikel 1 in lichaam van de regeling, introductie door bevoegd gezag gm0503 in versie v0.1art_1gm0503_v0-1__art_1
2Een tweede artikel genummerd met "1" in lichaam van dezelfde regeling, introductie in versie v1.6. (Dit zou niet voor mogen komen; eId en wId van het eerste artikel blijven ongewijzgd)art_1_inst2gm0503_v1-6__art_1_inst2
3Vernummering van het tweede "Artikel 1" naar "1a" in versie v1.7art_1agm0503_v1-6__art_1_inst2
4Een artikel 10:2 in hoofdstuk 10 van een regeling, introductie door bevoegd gezag mn002 in versie 2018-25-10chp_10__art_10.2mn002_2018-25-10__chp_10__art_10.2
5Lid 1. in voorgaand artikel 10:2chp_10__art_10.2__para_1mn002_2018-25-10__chp_10__art_10.2__para_1
6Na plaatsen van bestaande artikel 10:2 binnen een nieuwe paragraaf 10.1 in versie 2019-01-09chp_10__subsec_10-1__art_10.2mn002_2018-25-10__chp_10__art_10.2__para_1
7Aanhef, een van de elementen met een vast eId / wIdformula_1formula_1
8Sluiting direct na het lichaam, een van de elementen met een vast eId / wIdformula_2formula_2
9Sluiting in de daaropvolgende bijlageformula_2_inst2formula_2_inst2
10Het derde item in een ongenummerde lijst; binnen wId is het versienummer een UUIDlist_o_1__item_o_3

mn000__

518d67613862486c9121784868d047e6

__list_o_1__item_o_3

11Toelichting, element met een vast eId / wIdrecitalrecital
12Artikelgewijze Toelichting, al dan niet binnen een Toelichting, element met een vast eId / wIdartrectialartrecital
13Eerste divisietekst van een Artikelgewijze Toelichting die binnen de Toelichting staatartrecital__content_o_1mn002__2018-25-10__artrecital__content_o_1