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]

Naar mijn weten is er geen verdere feedback van TO-leden tot nu toe, dus ik heb het label "Ter goedkeuring" toegevoegd voor bespreking op het TO van 2 december.

Het voorstel vanuit TO-leden is om tijdens het TO deze wijziging vast te stellen, maar daarna nog een consultatie te doen specifiek bij het Kennisplatform API's. Op basis van de feedback kunnen we dan in het eerste TO van 2026 de definitieve vaststelling in het TO doen en deze wijziging doorvoeren.

[TimvdLippe]

Enkele linter regels geschreven. Hierbij de resultaten:

Statistics for rule nlgov:date-time-ensure-timezone:

Analyzed: 160
Passing: 160
Percentage: 100%

Statistics for rule nlgov:time-without-timezone:

Analyzed: 160
Passing: 156
Percentage: 97%

Statistics for rule nlgov:specify-format-for-date-and-time:

Analyzed: 160
Passing: 140
Percentage: 87%

Statistics for rule nlgov:use-date-instead-of-datetime:

Analyzed: 160
Passing: 152
Percentage: 95%

Interessante bevindingen:

1. De heuristieken werken best wel redelijk. Het is lastig om te bepalen wanneer iets een datum had moeten zijn, maar door op basis van tekst wat aannames te doen lijken er de correcte gevallen uitgepikt te worden.
2. We zeggen iets over fields, maar moeten we ook iets zeggen over parameters? Dat wordt nog best vaak gebruikt.
3. Moeten we enkel time-local toestaan of is time soms ook toegestaan? E.g. met tijdzone, maar dan zonder datum.

Voor dat laatste punt, wat denken we van dit soort gevallen? Volgens mij hebben ze hier time-local bedoeld ipv time (zie beschrijving op https://spec.openapis.org/registry/format/):

{
  "name": "tijdstipWeging[in]",
  "in": "query",
  "description": "Matches any value from a comma-separated list: val1,val2,valN.",
  "schema": {
    "type": "array",
    "items": {
      "type": "string",
      "format": "time"
    }
  },
  "explode": false,
  "style": "form"
},

[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.