From 3404b3a42f81c1c419aa9853ec27da41ee7abb09 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 14:04:56 +0100 Subject: [PATCH 1/2] String format/pattern recommendation --- documentation/API-design-guidelines.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..51cf0380 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1337,14 +1337,15 @@ This part describes the list of possible messages returned by the API. It also i This part captures a detailed description of all the data structures used in the API specification. For each of these data, the specification must contain: - Name of the data object, used to reference it in other sections. - Data type (String, Integer, Object…). -- If the format of a string is date-time following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)` +- If the data type is string it is recommended to use appropriate modifier property `format` and/or `pattern` whenever possible. The [OpenAPI Initiative Formats Registry](https://spec.openapis.org/registry/format/) contains the list of formats used in OpenAPI specifications. + - If the format of a string is date-time following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)` - If the data type is an object, list of required properties. - List of properties within the object data, including: - Property name - Property description - Property type (String, Integer, Object …) - Other properties by type: - - String ones: min and max longitude + - String ones: min and max length - Integer ones: Format (int32, int64…), min value. From aac5c39e7c41b3952620ea198008f12f772481e8 Mon Sep 17 00:00:00 2001 From: Rafal Artych <121048129+rartych@users.noreply.github.com> Date: Wed, 6 Nov 2024 14:38:26 +0100 Subject: [PATCH 2/2] Update documentation/API-design-guidelines.md Co-authored-by: Eric Murray --- documentation/API-design-guidelines.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index 51cf0380..5a840702 100644 --- a/documentation/API-design-guidelines.md +++ b/documentation/API-design-guidelines.md @@ -1338,7 +1338,7 @@ This part captures a detailed description of all the data structures used in the - Name of the data object, used to reference it in other sections. - Data type (String, Integer, Object…). - If the data type is string it is recommended to use appropriate modifier property `format` and/or `pattern` whenever possible. The [OpenAPI Initiative Formats Registry](https://spec.openapis.org/registry/format/) contains the list of formats used in OpenAPI specifications. - - If the format of a string is date-time following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)` + - If the format of a string is `date-time`, the following sentence must be present in the description: `It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z)` - If the data type is an object, list of required properties. - List of properties within the object data, including: - Property name