developer.overheid.nl

Ontwikkelaarsportaal van de Nederlandse overheid

Ga naar hoofdinhoud

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

Wat dit betekent voor je waarden​

WaardeOordeel
2026-10-08T09:00:00ZGoed, UTC
2026-10-08T11:00:00+02:00Goed in een request, in een response liever UTC
2026-10-08T09:00:00Fout, geen offset
1760000000Fout, 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:

voorbeeld van een response body
{
"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:

/openapi.yaml
geboortetijdTijdzone:
type: string
pattern: "^[+-][0-9]{2}:[0-9]{2}$"
examples:
- "+02:00"