Added /core/date-time

[sanderke]

Voorzet voor regel voor datum en tijd

closes #195

[github-actions]

Preview link voor pull request
Diff met W3CDiff

[TimvdLippe]

Ziet er goed uit! 2 kleine wijzigingen, de rest lijkt mij voldoende om te bespreken in het TO.

[TimvdLippe]

Willen we misschien ook nog bepaalde namen van velden vastleggen? Dus als er een datum is, dan moet het veld "date", "datum", "_date" of "_datum" heetten. En als het een timestamp is, dan moet het veld "timestamp", "tijdstip", "_timestamp" of "*_tijdstip" heetten.

[TimvdLippe]

Nog wat kleine fixes. De andere vragen moeten we offline even bespreken wat we daar mee willen.

[TimvdLippe]

https://swagger.io/docs/specification/v3_0/data-models/data-types/#strings geeft aan dat openapi een "format": "date" volgens RFC 9557 kan aangeven.

Tevens lijkt RFC 9557 een restrictie te zijn op ISO8601 waarbij er minder mogelijkheden te zijn. Deze RFC is relevant voor internet protocollen, dus lijkt het beter om deze RFC te gebruiken ipv de ISO standaard.

Wat betreft de veldnamen laten we dat voor nu buiten de regel. We gaan dit op het TO bespreken of hier alsnog een restrictie op moet plaatsvinden.

De linter check laten we nog even achterwege, omdat we niet goed weten hoe je dit geautomatiseerd kan testen als we enkel een "type": "string" hebben in de openapi specification.

[BvanRaaij]

Hi Tim, in de concept ADR staat dat alle datetimes het ISO 8601 format YYYY-MM-DDTHH:mm:ssZ moeten hebben. Ik vraag me af of dit handig is. De Z betekent Zulu time, ofwel UTC+00:00. Met de keuze voor dit format verplicht je dus iedereen alle data-tijden om te zetten in timezone +:00:00 (wat in de wintertijd 1 uur en in de zomertijd 2 uur verschilt met onze tijd) en weer terug. Het is misschien logischer (zeker met toepassingen die vooral in de Nederlandse context gebruikt worden) om het format YYYY-MM-DDTHH:mm:ss**+/-hh:mi** ook toe te staan of zelfs voor te schrijven

Verder detail: volgens mij schrijf je de uren als hh, niet als HH (zie https://www.w3.org/TR/NOTE-datetime).

[TimvdLippe]

Deze wijziging is goedgekeurd bij het TO 2025-12-02 voor consultatie bij Kennisplatform API's. Dat houdt in dat we het hoofdstuk "Date & Time" als geheel consulteren.

Tevens was er nog een behoefte aan een aparte regel dat als er zowel een tijd als datum veld apart in een response zitten, die moeten worden samengevoegd tot 1 veld.

Daarnaast nog een noot toevoegen dat er goed moet worden nagedacht als er enkel time wordt gebruikt, maar met een terugkerend patroon. In dat geval kan het in de tijdzone overgang vallen, waar de tijdzone van belang is. In dat geval is een datetime waarschijnlijk geschikter.

Niet meer relevant

[bwbroersma]

It's not ideal to require the intersection of ISO 8601 and some RFCs, since the ISO standard is not open.

[TimvdLippe]

Samen met Benjamin dat probleem verholpen door uit te leggen wat het verschil is tussen RFC9557 en ISO8601.

[KlaasBaarssen]

Het punt is duidelijk verbeterd, maar 1 zorgpunt blijft. Dit gaat over interpretatie van een gegeven.
In de tekst staat het al: geboortedatum. Het is mij niet duidelijk hoe voorkomen wordt of een datetime wel of niet geconverteerd mag worden naar lokale tijd. In het voorbeeld van geboortedatum 2025-03-20T00:00:00+01:00, timezone conversion would result in 2025-03-19T23:00:00Z
Voor een vergadering is het wel handig dat een date-time wordt opgezet naar lokale tijdzone, dit om te zorgen dat de medewerker in de andere tijdzone er op het juiste tijdstip is.
Na het lezen over de verschillende types is het voor mij niet duidelijk welk type ik moet inzetten om conversie aan te moedigen of juist te ontmoedigen.

[TimvdLippe]

/core/date-time/date-omit-time-portion schrijft voor dat als het tijdzone-component niet relevant is, er een date moet worden gebruikt in plaats van datetime. Verduidelijkt dat de situatie?

In het geval van een geboortedatum is de tijdzone dus niet relevant, dus moet het date zijn. Voor een vergadering is de tijdzone wel relevant, dus is het datetime.

Voor verdere achtergrond, zie ook https://apiux.com/2013/03/20/5-laws-api-dates-and-times/ (law 5) waar dit op gebaseerd is. Deze blogpost is de basis voor alle regels in het "Date & Time" hoofdstuk en is internationaal erkend als de facto standaard hoe om te gaan met datum en tijd.

[KlaasBaarssen]

/core/date-time/date-omit-time-portion schrijft voor dat als het tijdzone-component niet relevant is, er een date moet worden gebruikt in plaats van datetime. Verduidelijkt dat de situatie?

In het geval van een geboortedatum is de tijdzone dus niet relevant, dus moet het date zijn. Voor een vergadering is de tijdzone wel relevant, dus is het datetime.

Voor verdere achtergrond, zie ook https://apiux.com/2013/03/20/5-laws-api-dates-and-times/ (law 5) waar dit op gebaseerd is. Deze blogpost is de basis voor alle regels in het "Date & Time" hoofdstuk en is internationaal erkend als de facto standaard hoe om te gaan met datum en tijd.

Geboortedatum is vaak een date, maar in een geboorteakte vaak een datetime, omdat daar tijdstip van geboorte bij staat. Het gekke is dat als je die datum wel converteert naar lokale tijd het technisch klopt. Stel in NL geboren om 14:00+2 dan is het voor UK 12:00+0 geboren. Klopt technisch, maar wenselijk.....
Daarnaast heb je bijv. rondom een zoekfunctie met datum+tijd een uitdaging. Stel je server draait in US en je bent in NL en geeft aan dat je alle reserveringen wilt zien voor dag X tussen 14:00 en 15:00. Als dit met tijdzone wordt gestuurd van NL (+ 1 of + 2), moet de server dit omzetten naar US tijdzone (meerdere opties) en krijg je de reserveringen terug die tussen 14:00 en 15:00 in NL-tijd, maar US-tijd paar uur eerder. Het kan dat je dit wilt, maar ook niet afhankelijk of boekingstijden NL of US tijden zijn. En deze onduidelijkheid wordt niet weggenomen met deze ADR.

[TimvdLippe]

Het punt van Klaas met hem besproken en zojuist een update gepusht waarbij het gedeelte van de noot over "als de timezone offset relevant is" verplaatst naar de statement. Tevens 2 voorbeelden toegevoegd voor die scenario's en hoe daar dan mee om moet worden gegaan.

[TimvdLippe]

Deze wijziging is goedgekeurd op het TO API van 2026-03-03.

[BvanRaaij]

Mooi resultaat!