From 7eef0865df1482863f1347d1920e2a4e8dfdf32f Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Thu, 24 Jul 2025 16:52:10 +0200 Subject: [PATCH 01/10] Added `/core/date-time` --- sections/designRules.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/sections/designRules.md b/sections/designRules.md index 95403e7..7451938 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -125,6 +125,22 @@ A resource that corresponds to a single conceptual entity is referred to as a [= +
+

Use ISO 8601 for date and time formats

+
+
Statement
+
+

All date and time fields in requests and responses MUST be in ISO 8601 format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). The response MUST be in UTC. While the request can have a time offset, storing SHOULD be done in UTC.

+

If the time is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

+
+
Rationale
+
+

Implementing ISO 8601 in UTC removes ambiguity in date handling between systems and timezones.

+

Inserting a default or irrelevant time can lead to interpretation errors in international contexts. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich.

+
+
+
+ ## HTTP methods Although the REST architectural style does not impose a specific protocol, REST APIs are typically implemented using HTTP [[rfc9110]]. From 8b98d6f88017f09040e0ec47d17af5e1603f6741 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Thu, 24 Jul 2025 16:57:50 +0200 Subject: [PATCH 02/10] markdownlint --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index 7451938..375f984 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -131,7 +131,7 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
Statement

All date and time fields in requests and responses MUST be in ISO 8601 format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). The response MUST be in UTC. While the request can have a time offset, storing SHOULD be done in UTC.

-

If the time is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

+

If the time is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

Rationale
From c982b064d49f53c8bfc7d5c21ca9ab84b91c65d4 Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Wed, 13 Aug 2025 16:02:02 +0200 Subject: [PATCH 03/10] Apply suggestions from code review Co-authored-by: Tim van der Lippe --- sections/designRules.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 375f984..c77f4f6 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -130,8 +130,8 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
Statement
-

All date and time fields in requests and responses MUST be in ISO 8601 format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). The response MUST be in UTC. While the request can have a time offset, storing SHOULD be done in UTC.

-

If the time is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

+

All date and time fields in requests and responses MUST be in ISO 8601 format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). Fields in responses MUST be in UTC. Fields in requests MUST allow any time offset, which servers SHOULD normalize to (and store in) UTC.

+

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

Rationale
From 00ae4402c9260d67ad09912671a76afd6f27f16e Mon Sep 17 00:00:00 2001 From: Alexander Green Date: Fri, 22 Aug 2025 11:36:12 +0200 Subject: [PATCH 04/10] Update sections/designRules.md Co-authored-by: Tim van der Lippe --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index c77f4f6..f4d8ec1 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -130,7 +130,7 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
Statement
-

All date and time fields in requests and responses MUST be in ISO 8601 format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). Fields in responses MUST be in UTC. Fields in requests MUST allow any time offset, which servers SHOULD normalize to (and store in) UTC.

+

All date and time fields in requests and responses MUST follow [[RFC9557]] and thus be in [[ISO8601]] format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). Fields in responses containing timestamps MUST be in UTC (e.g. Z as offset). APIs MUST accept fields with timestamps with any time offset in requests and servers SHOULD normalize to (and store in) UTC.

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

Rationale
From 00d20c4c791a3655df297509123dbe56c9021126 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 11:20:38 +0200 Subject: [PATCH 05/10] Verwerk feedback op basis van werksessie --- sections/designRules.md | 67 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 62 insertions(+), 5 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index f4d8ec1..c2acd82 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -125,18 +125,75 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
-
+## Date and time + +

Use ISO 8601 for date and time formats

Statement
-

All date and time fields in requests and responses MUST follow [[RFC9557]] and thus be in [[ISO8601]] format (e.g., YYYY-MM-DD for dates, YYYY-MM-DDTHH:mm:ssZ for timestamps). Fields in responses containing timestamps MUST be in UTC (e.g. Z as offset). APIs MUST accept fields with timestamps with any time offset in requests and servers SHOULD normalize to (and store in) UTC.

-

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted, stored, and returned.

+

All date, datetime and time fields in requests and responses MUST adhere to [[RFC9557]] and [[ISO8601]] format. Each field in the OpenAPI specification MUST set "type": "string" and set "format" to the OpenAPI format as listed in the following table: + + + + + + + + + + + + + + + + + + + + + + + + + +
Field typeISO8601 formatOpenAPI format
Datefull-date (YYYY-MM-DD)"format": "date"
Datetimedate-time (YYYY-MM-DDThh:mm:ssZ or YYYY-MM-DDThh:mm:ss±hh:mm)"format": "date-time"
Timetime (hh:mm:ss)"format": "time-local"
+

+
Rationale
+
+

Implementing RFC9557 and ISO 8601 in UTC removes ambiguity in date handling between systems and timezones.

+
+
+
+ +
+

Allow all timezones in requests and use UTC in responses

+
+
Statement
+
+

Fields in responses containing timestamps MUST be in UTC (e.g. Z as offset). APIs MUST accept fields with timestamps with any time offset in requests. +

+
Rationale
+
+

TODO +

+
+
+ +
+

Omit time portion for date fields

+
+
Statement
+
+

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted and returned.

Rationale
-

Implementing ISO 8601 in UTC removes ambiguity in date handling between systems and timezones.

-

Inserting a default or irrelevant time can lead to interpretation errors in international contexts. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich.

+

Appending a default or irrelevant time portion to a date field can lead to interpretation errors. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich. +

From 375c4d96564eb5982202fe1513602bdeb54806c1 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 11:42:11 +0200 Subject: [PATCH 06/10] Vul tekst in bij TODOs --- sections/designRules.md | 18 +++++++++++------- 1 file changed, 11 insertions(+), 7 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index c2acd82..ea73655 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -128,11 +128,11 @@ A resource that corresponds to a single conceptual entity is referred to as a [= ## Date and time
-

Use ISO 8601 for date and time formats

+

Use standard format for date, datetime and time

Statement
-

All date, datetime and time fields in requests and responses MUST adhere to [[RFC9557]] and [[ISO8601]] format. Each field in the OpenAPI specification MUST set "type": "string" and set "format" to the OpenAPI format as listed in the following table: +

All date, datetime and time fields in requests and responses MUST adhere to [[RFC9557]] and [[ISO8601]] format. Each field in the OpenAPI specification MUST set "type": "string" and set "format" to the OpenAPI format as listed in the following table: @@ -172,11 +172,11 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
Statement
-

Fields in responses containing timestamps MUST be in UTC (e.g. Z as offset). APIs MUST accept fields with timestamps with any time offset in requests. +

APIs MUST accept fields with timestamps with any timezone offset in requests. Fields in responses containing timestamps MUST be in UTC (e.g. Z as timezone offset).

Rationale
-

TODO +

Allowing clients to use any timezone offset in requests results in flexibility and less complexity for users. Using UTC in responses results in clarity and removes ambiguity.

@@ -191,13 +191,17 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
Rationale

Appending a default or irrelevant time portion to a date field can lead to interpretation errors. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich. -

+Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients. + + + ## HTTP methods Although the REST architectural style does not impose a specific protocol, REST APIs are typically implemented using HTTP [[rfc9110]]. From b61be80b05a0a65d0c1832c7cb12517157c46c36 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 11:48:59 +0200 Subject: [PATCH 07/10] Update de bewoording --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index ea73655..35be616 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -198,7 +198,7 @@ A resource that corresponds to a single conceptual entity is referred to as a [= Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients. From 89fc8bc05ec6e8076bd7843c534a14f094aeb1e4 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 11:58:50 +0200 Subject: [PATCH 08/10] Zet het voorbeeld voor de regels --- sections/designRules.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 35be616..236b6ac 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -127,6 +127,13 @@ A resource that corresponds to a single conceptual entity is referred to as a [= ## Date and time +Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients. + + +

Use standard format for date, datetime and time

@@ -195,13 +202,6 @@ A resource that corresponds to a single conceptual entity is referred to as a [=
-Handling date and time is tricky and can lead to confusion among clients. The date-time rules remove ambiguity and provide clarity in the API contract between servers and clients. - - - ## HTTP methods Although the REST architectural style does not impose a specific protocol, REST APIs are typically implemented using HTTP [[rfc9110]]. From daaefa1b222798638ae2a7a78f6435d524b72a88 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 12:11:31 +0200 Subject: [PATCH 09/10] Update bewoording --- sections/designRules.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sections/designRules.md b/sections/designRules.md index 236b6ac..ee3f3d0 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -175,11 +175,11 @@ Handling date and time is tricky and can lead to confusion among clients. The da
-

Allow all timezones in requests and use UTC in responses

+

Allow all timezone offsets in requests and use UTC in responses

Statement
-

APIs MUST accept fields with timestamps with any timezone offset in requests. Fields in responses containing timestamps MUST be in UTC (e.g. Z as timezone offset). +

APIs MUST accept any timezone offset in fields in requests containing a datetime. Fields in responses containing a datetime MUST be in UTC (e.g. Z as timezone offset).

Rationale
@@ -188,12 +188,12 @@ Handling date and time is tricky and can lead to confusion among clients. The da
-
+

Omit time portion for date fields

Statement
-

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) SHOULD be accepted and returned. +

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) MUST be accepted and returned.

Rationale
From aca3229c654b423fc36757dd6cb94cae7acceacc Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 23 Oct 2025 14:15:47 +0200 Subject: [PATCH 10/10] Update bewoording --- sections/designRules.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sections/designRules.md b/sections/designRules.md index ee3f3d0..c812fe1 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -193,7 +193,7 @@ Handling date and time is tricky and can lead to confusion among clients. The da
Statement
-

If the time portion is not relevant, only the date portion (e.g., YYYY-MM-DD) MUST be accepted and returned. +

If the time portion is not relevant, date MUST be used instead of datetime.

Rationale