diff --git a/documentation/API-design-guidelines.md b/documentation/API-design-guidelines.md index cac51128..5a840702 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`, 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 - 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.