/core/date-time/timezone
Een API moet elke tijdzone-offset accepteren in velden met een datumtijd in
een request. In een response hoort een datumtijd in UTC te staan, dus met
Z als offset. Is de oorspronkelijke tijdzone relevant voor gebruikers, dan
moet de offset daarnaast worden opgeslagen en gepubliceerd in een apart
veld, in het ISO 8601-1-formaat time-offset.
Het verschil is bewust. Een client ergens anders in de wereld mag +05:30
sturen zonder dat de API hem afwijst; wat de API teruggeeft is één vorm, zodat
afnemers niet elk hun eigen conversie hoeven te doen.
- Regel: https://gitdocumentatie.logius.nl/publicatie/api/adr/#/core/date-time/timezone
- Linterregels:
nlgov:date-time-ensure-timezone,nlgov:time-without-timezone
Wat dit betekent voor je waarden
| Waarde | Oordeel |
|---|---|
2026-10-08T09:00:00Z | Goed, UTC |
2026-10-08T11:00:00+02:00 | Goed in een request, in een response liever UTC |
2026-10-08T09:00:00 | Fout, geen offset |
1760000000 | Fout, epoch in plaats van een datumtijd |
Een veld met "format": "time-local" is de uitzondering: dat is per definitie
een kloktijd zonder zone. Gebruik dat alleen als de zone echt niet van
toepassing is, zoals een openingstijd.
Oorspronkelijke tijdzone bewaren
Een datumtijd in UTC zegt niet meer in welke tijdzone de waarde is
geregistreerd. Is dat relevant voor gebruikers, publiceer de offset dan in een
eigen veld. Een geboortetijd in Nederland krijgt bijvoorbeeld een apart veld met
+01:00 of +02:00:
{
"geboortetijd": "2026-10-08T09:00:00Z",
"geboortetijdTijdzone": "+02:00"
}
Voor time-offset bestaat geen format in OpenAPI, dus beschrijf het veld als
"type": "string" met een pattern:
geboortetijdTijdzone:
type: string
pattern: "^[+-][0-9]{2}:[0-9]{2}$"
examples:
- "+02:00"