date-time velden in de BAG API Individuele Bevragingen missen een tijdzone en zijn daarom geen geldige date-time velden

[edgarvonk]

De OpenAPI specificatie van de BAG API gebruikt het formaat 'date-time' voor datum-tijd velden. Echter de API voldoet hier bij mijn weten niet aan omdat de datum-tijd velden waardes hebben zonder een tijdzone. Dit is weliswaar compliant met de ISO 8601 spec maar volgens mij niet met de RFC 3339 waar de OpenAPI standaard van uit gaat: https://spec.openapis.org/registry/format/date-time. Wat op https://docs.geostandaarden.nl/api/API-Strategie-ext/#temporal wordt geschreven is volgens mij daarom niet correct. In de OpenAPI JSON standaard moet een date-time veld daarom altijd een tijdzone hebben.

Het veel gebruikte OpenAPI Generator framework gaat hier ook van uit. Het gevolg is dat wij geen (Java) stub code kunnen generen van de BAG API met de standaard configuratie met de OpenAPI Generator omdat deze van alle date-time velden standaard een Java OffsetDateTime maakt waar een tijdzone verplicht is. Bijv 2014-01-10T20:43:29 voldoet wel aan ISO 8601 maar niet aan RFC 3339 en is geen valide OpenAPI date-time. Kan dit aangepast worden?

[strijm]

Dank voor je terugkoppeling.

Samenvatting:
M.i. hebben we hier te maken met een 'inconsistentie' tussen specificaties / standaarden. We kunnen het tijdstipformaat niet aanpassen in de API specificatie omdat dat een breaking change betekent die impact heeft op de hele BAG keten (bronhouders, landelijke voorziening en afnemers). Daarnaast zou het aanpassen van het tijdstip formaat betekenen dat we niet meer aan een aantal specificaties voldoen waar we aan moeten voldoen en waar we nu ook aan voldoen. De geldende specificaties zullen dan eerst aangepast moeten worden zodanig dat ze consistent zijn met elkaar. Het maken van een nieuwe major versie van de BAG Individuele Bevragingen API zou een oplossing kunnen bieden, ware het niet dat ook die aan de dan geldende specificaties/standaarden zal moeten voldoen. Voor een grote deel betreft het dezelfde specificaties die voor de huidige BAG IB API versie gelden. Er zal goed naar de ontwikkelingen van de standaarden gekeken moeten worden, zowel degene die reeds plaats hebben gevonden als de nog te verwachten ontwikkelingen.
Hieronder een gedetailleerde toelichting.

Huidige situatie:
BAG Individuele Bevragingen API specificatie voldoet qua tijdstippen aan:

• BAG Catalogus 2018 par. 4.7 en 9.1.4.
  De BAG IB API is gericht op gebruik binnen Nederland (excl. BES eilanden). In Nederland kennen we maar één tijdzone, er is dan geen noodzaak om de tijdzone te registreren. Bij BAG is ervoor gekozen de lokale datum en tijd te registreren en uit te wisselen (dus niet t.o.v. UTC en zonder tijdzonde), dit is vastgelegd in de BAG Catalogus 2018 en is conform ISO 8601.
• ISO 8601:2004 zoals vermeldt in BAG Catalogus 2018 par. 4.7.
  Zie omschrijving vorige punt. De ISO 8601 specificatie biedt de mogelijk tijdstippen zonder tijdzone te registreren, dit wordt gezien als lokale tijd. De ISO 8601 standaard sluit het gebruik van tijdzone niet uit. Het is aan een registratie om hier afspraken over te maken.
• Datum en tijd standaard (NEN-ISO 8601:2019)
  Deze standaard staat vermeld op de lijst van Aanbevolen standaarden op het Forum standaardisatie.
• NL API Design Rules Extensions IIb Temporal wat een extensie is op de NL API Design Rules 1.0 zoals vermeld in de lijst van Verplichte standaarden op het Forum standaardisatie wordt gerefereerd naar RFC3339 en ISO 8601. Tevens wordt het datum en tijd formaat beschreven voor tijdreis query parameters zonder tijdzone. Dit formaat voldoet aan ISO 8601 en BAG Catalogus 2018. Dit formaat geeft aan dat de standaard gericht is op ontwikkeling van API's voor gebruik in Nederland met lokale datum en tijd v.w.b. tijdreis query parameters. De BAG IB API voldoet aan deze specificatie v.w.b. de tijdreis query parameters. Er wordt in de NL API Design Rules (Extensions) verder nergens benoemd in welk formaat datum en tijd uitgewisseld moeten worden. Vanwege consistentie en compliance met ISO 8601 en BAG Catalogus 2018 hanteert de BAG IB API daarom overal dit formaat.

BAG Individuele Bevragingen API specificatie voldoet mogelijk niet aan:

• NL API Design Rules Extensions IIb Temporal
  Dit is een extensie op de NL API Design Rules 1.0 zoals vermeld in de lijst van Verplichte standaarden op het Forum standaardisatie. In deze extensie wordt gerefereerd naar RFC3339 en ISO 8601. Tevens wordt het datum en tijd formaat beschreven voor tijdreis query parameters zonder tijdzone. Dit formaat voldoet aan ISO 8601 maar strikt genomen niet aan RFC3339. Het is echter niet mogelijk om zonder aanpassing van het formaat aan zowel ISO 8601 als RFC3339 te voldoen (zie hieronder). Er wordt in de NL API Design Rules verder nergens benoemd in welk formaat datum en tijd uitgewisseld moeten worden. Dat maakt het lastig om te beoordelen of er aan de NL API Design Rules (Extensions) standaard wordt voldaan.
• OpenAPI Specification 3.0.x par. 4.4 Data types. De OpenAPI specificatie 3.0.x refereert naar RFC3339 par. 5.6 in het kader van het date-time data type. RFC3339 specificeert een datum tijd formaat waarbij UTC als basis geldt en een tijdzone verplicht is. RFC3339 is daarmee wel compliant aan ISO 8601, maar is strikter en implementeert niet alle mogelijkheden van de ISO 8601, omdat een optioneel deel verplicht is gemaakt en er slechts één uitgangspunt is (tijdstippen t.o.v. UTC) in plaats van ook lokale tijd (niet t.o.v. UTC en zonder tijdzone) toe te staan. Dit betekent minder flexibiliteit: RFC3339 tijdstippen voldoen wel aan ISO 8601, maar ISO 8601 tijdstippen voldoen niet altijd aan RFC3339. Aan de andere kant is het toepassen van het datum en tijd formaat in de RFC3339 aanbevolen (SHOULD in RFC2119 termen) en niet verplicht (MUST in RFC 2119 termen) voor nieuwe protocollen, dus in die zin biedt dit nog steeds de mogelijkheid om hiervan af te wijken, mits voor alle partijen duidelijk is hoe de tijd geïnterpreteerd dient te worden. M.i. is dat bij BAG het geval doordat aan alle overige geldende standaarden wordt voldaan (zie hierboven).
  Ter informatie: OpenAPI Specification 3.1.x stelt niet meer dat datum en tijd moeten voldoen aan RFC3339, omdat dit beter overeenkomt met het JSON schema 2020-12 (waar OAS 3.1.x op is gebaseerd), wat meer flexibiliteit biedt, iets wat ISO 8601 al doet. OpenAPI Specification 3.0.x (RFC3339) beveelt aan om de tijdzone op te nemen.

Gewenste situatie
RFC3339 stelt dat alle datum en tijdstippen die via internet worden uitgewisseld t.o.v. UTC moeten zijn incl. een tijdzone. Daar is iets voor te zeggen omdat het eenduidig is en in alle situaties waarbij data over verschillende tijdzones worden uitgewisseld, het altijd duidelijk is hoe deze geïnterpreteerd moet worden.
Alle geldende specificaties en standaarden komen met elkaar overeen.

Gap analyse:
De BAG IB API moet voldoen aan de NL API Strategie specificaties maar die is ambigu op dit vlak en geeft daardoor geen uitsluitsel over in welk formaat datum en tijd uitgewisseld moeten worden in REST APIs (afgezien van tijdreis query parameters).
De BAG IB API moet voldoen aan OpenAPI Specification 3.0.x, deze verwijst naar RFC3339. RFC3339 specificeert een strikter datum en tijd formaat dan ISO 8601, waardoor datum en tijd wel coform ISO 8601 en niet conform RFC3339 kunnen zijn. Een datum en tijd die conform RFC3339 zijn, zijn ook altijd conform ISO 8601.
De BAG IB API moet voldoen aan de BAG Catalougs 2018 en ISO 8601. De BAG IB API voldoet hier nu aan omdat er een datum en tijd formaat wordt gebruikt dat conform ISO 8601 is. Dit formaat is echter niet conform RFC3339 waardoor niet aan deze en niet aan OpenAPI Specification 3.0.x wordt voldaan.
Dat de API zowel aan de RFC3339 als aan ISO 8601 moet voldoen, levert dus een conflict op.

Conclusie:
Doordat de OpenAPI Specification 3.0.x op de lijst van verplichte standaarden staat en ISO 8601 op de lijst van aanbevolen standaarden zou je kunnen stellen dat de OpenAPI Specification 3.0.x prevaleert boven de ISO 8601. Echter de BAG keten moet ook voldoen aan de BAG Catalogus 2018 (en dus aan ISO 8601) en doet dat nu ook. Aangezien in RFC3339 het datum en tijd formaat wordt aanbevolen en niet verplicht wordt gesteld en we ook aan ISO 8601 moeten voldoen volgens de BAG catalogus hoeven we stikt genomen niets te wijzigen. Sterker nog door wijzigingen door te voeren zouden we niet meer voldoen aan de BAG Catalogus en daarmee impact in de BAG keten veroorzaken.
De beslissing om tijdstippen t.o.v. UTC en incl. een tijdzone te gebruiken kan niet door één partij in een keten maar alleen in samenspraak met alle partijen in die keten genomen worden. Dit maakt het geen gemakkelijke aanpassing. Er moet een hele goede reden voor zijn om een dergelijke verandering en investering te verantwoorden.
De redenatie om tijdstippen t.o.v. UTC en incl. een tijdzone uit te wisselen en daarmee aan de RFC3339 te voldoen, is op zich goed omdat het e.e.a. eenduidig maakt wanneer data over verschillende tijdzones wordt uitgewisseld. Nederland (excl. BES eilanden) kent echter maar één tijdzone. Alle data wordt in dezelfde tijdzone geregistreerd en uitgewisseld. APIs zijn vooral gericht op het uitwisselen van data binnen Nederland (excl. BES eilanden). In die gevallen waar van toepassing, ondersteunt ISO 8601 het gebruik van tijdzones en kan voor de desbetreffende API specificatie vastgelegd worden dat datum en tijd in UTC incl. een tijdzone worden vastgelegd en uitgewisseld. Omdat in die gevallen het tijdstip in UTC incl. tijdzone moet zijn, wordt tevens voldaan aan RFC3339.
De BAG is gericht op het gebruik in Nederland (excl. BES eilanden). Het is m.i. op dit moment valide dat lokale tijdstippen gebruikt worden en geen UTC tijdstippen incl. tijdzone en het biedt weinig meerwaarde de datum en tijd t.o.v. UTC en incl. tijdzone te registreren.
De OpenAPI Specification 3.0.x verwijst naar de RFC3339, maar versie 3.1.x doet dat niet meer. Dit geeft aan dat er in het algemeen meer flexibiliteit gewenst is v.w.b. datum en tijd uitwisseling bij REST API's, flexibiliteit die de ISO 8601 op dit moment al biedt.
Alles afwegende zie ik op dit moment geen mogelijkheid, duidelijk aanwijsbare reden of meerwaarde om de BAG IB API aan te passen zodat deze aan RFC3339 voldoet. Dat wil niet zeggen dat het in de toekomst niet mogelijk is om dit wel te doen.

Advies:
Om in de toekomst de geldende standaarden beter op elkaar te laten aansluiten is het mogelijk wijzigingsverzoeken in te dienen. De vraag is dan op welke standaard/specificatie een wijzigingsverzoek ingediend moet worden.
Een wijzigingsverzoek indienen op RFC3339 of ISO 8601 heeft, ondanks dat dit de bronnen zijn, weinig kans van slagen omdat beide een eigen visie en doel hebben en die kunnen onverenigbaar zijn.
De OpenAPI Specification 3.0.x verwijst naar RFC3339 en beperkt de toepassing tot REST API specificaties. Een wijzigingsverzoek indienen op de OpenAPI Specification 3.0.x heeft niet zoveel zin, want er is al een 3.1.x versie en daarin wordt niet meer verwezen naar RFC3339. Deze versie staat alleen nog niet op de lijst van verplichte standaarden van het Forum standaardisatie. Ter info: een verzoek hiertoe is afgewezen omdat de OpenAPI Specification 3.1.x weliswaar een minor versie upgrade is t.o.v. 3.0.x maar deze bevat wel breaking changes. Zie hier een voorbeeld daarvan.
Blijft over het indienen van een wijzigingsverzoek op de NL API Design Rules Extension en BAG Catalogus 2018.

1. WIjzigingsverzoek op de NL API Design Rules Extension IIb Temporal

Er zijn plannen om een Temporal module te maken. In die module kunnen dit soort tijd aspecten gestandaardiseerd worden. Er zijn twee mogelijke oplossingsrichtingen:
a. De specificatie wordt zodanig aangepast dat er (met het oog op OpenAPI Specification 3.1.x) een uitzondering wordt opgenomen dat er niet meer aan RFC3339 voldaan moet worden en alle verwijzingen naar RFC3339 worden verwijderd. Daarnaast moet een verwijzing worden opgenomen naar ISO 8601 als uitgangspunt.
b. De specificatie wordt zodanig aangepast dat datum en tijd formaat in UTC incl. een tijdzone verplicht worden gesteld zodat wordt voldaan aan ISO 8601 en RFC3339.

2. Wijzigingsverzoek op de BAG Catalogus 2018

Verzoek om het datum en tijd formaat aan te passen, zodanig dat datum en tijd niet meer in lokale tijd maar in UTC tijden incl. tijdzone worden geregistreerd en uitgewisseld.

Alleen door optie 1a wel en 2 niet door te voeren of 1b en 2 beide door te voeren, houden we de verschillende standaarden/specificaties consistent. Dit moet goed gecoördineerd worden bv. door het ministerie van VRO en het is aan alle keten partijen om te besluiten of deze wijzigingsverzoeken worden gehonoreerd of afgewezen.

[edgarvonk]

Dank voor de uitgebreide reactie @strijm ! Het zit duidelijk 'ietsje' complexer dan ik in eerste instantie dacht.. ;-).