Specify string format whenever possible

[patrice-conil]

Problem description
As in geofencing, I propose to constrain the string format whenever possible to simply implementation and clarify usage.

For example, everywhere we use notification :Geolocation, Qod, DeviceStatus and SimSwap ...

    NotificationUrl:
      type: string
      example: "https://application-server.com"
      description: https callback address where the event notification must be POST-ed

Would be

    NotificationUrl:
      type: string
      format: uri
      example: "https://application-server.com"
      description: https callback address where the event notification must be POST-ed

Expected action
Add paragraph in guidelinse to describe this

[rartych]

The living list of defined formats is in Formats Registry of OpenAPI Initiative.

[patrice-conil]

Thanks @rartych, I will reference "formats registry" in this explanatory paragraph if others agree

[rartych]

Formats Registry is created for OAS 3.1 to decouple format definitions from OpenAPI specification.

However, according to OAS spec:

the format property is an open string-valued property, and can have any value. Formats such as "email", "uuid", and so on, MAY be used even though undefined by this specification.

Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

Do we need CAMARA-specific formats?

[rartych]

Formats defined in OAS 3.0:

Common Name	type	format	Comments
integer	integer	int32	signed 32 bits
long	integer	int64	signed 64 bits
float	number	float
double	number	double
byte	string	byte	base64 encoded characters
binary	string	binary	any sequence of octets
date	string	date	As defined by full-date - [RFC3339]
dateTime	string	date-time	As defined by date-time - [RFC3339]

source: OAI/OpenAPI-Specification#2857 (comment)

[rartych]

@eric-murray Could add your comment about relationship between patterns and formats?

[eric-murray]

Valid strings can be qualified by both format and pattern, and both can be useful and, indeed, complementary. The value of format is that it can capture restrictions that are not easily expressed as a regex, and are usually intuitive to the API developer. The value of pattern is that patterns can be enforced automatically by code generators, whereas enforcing a format will depend upon the specific code generator functionality.

So I would not restrict the guidance to just formats. The recommendation should be that strings should be qualified by an appropriate format and/or pattern whenever possible.

I would avoid CAMARA-specific formats, and stick to those recognised by JSON.

[jlurien]

Reactivating this discussion. The reference to the accepted values of format between OAS 3.0 and 3.1 does not change that much:

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#data-types
https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#data-types

Both list some formats explicitly listed by OAS by do not exclude other values. Indeed we are using already formats as uuid or ipv4, that are not in the short list explicitly being defined by OAS 3.0.x. In the end it will depend on the specific tool to recognize and support other common formats automatically. We can always remark in the description of a property that the expected value must follow certain format as specified in ISO, RFC, JSON-schema, etc, and implementations may use any suitable tool to validate that.