Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Specify string format whenever possible #93

Open
patrice-conil opened this issue Nov 17, 2023 · 7 comments · May be fixed by #330
Open

Specify string format whenever possible #93

patrice-conil opened this issue Nov 17, 2023 · 7 comments · May be fixed by #330
Labels
documentation Improvements or additions to documentation Spring25

Comments

@patrice-conil
Copy link
Collaborator

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

@patrice-conil patrice-conil added the documentation Improvements or additions to documentation label Nov 17, 2023
@patrice-conil patrice-conil changed the title Precise string format each time it's possible Specify string format whenever possible Nov 17, 2023
@rartych
Copy link
Collaborator

rartych commented Nov 17, 2023

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

@patrice-conil
Copy link
Collaborator Author

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

@rartych
Copy link
Collaborator

rartych commented Nov 22, 2023

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
Copy link
Collaborator

rartych commented Dec 5, 2023

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
Copy link
Collaborator

rartych commented Dec 5, 2023

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

@eric-murray
Copy link
Collaborator

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
Copy link
Contributor

jlurien commented Feb 12, 2024

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation Spring25
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants