-
Notifications
You must be signed in to change notification settings - Fork 9.1k
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
version 3.0: additional formats #607
Comments
👍 |
The |
Rather than tightly couple to Slightly related, I would prefer not overloading Thus, while |
@DavidBiesack I actually intended
No objections to adding the concept of a role and an |
@ralfhandl Such things should be added into JSON Schema standard or extracted into a separate spec. I'm not against extending formats I just say that spec should reference some external doc and not to define them internally. |
@IvanGoncharov Looking at the list of formats supported by Swagger 2.0 we only find one format that is defined by JSON Schema: Formats are an explicit extension point of JSON Schema for semantic validation, and the OpenAPI Specification could be one of the "authoritative resources that accurately describes interoperable semantic validation". I'm not aware of other external documents describing formats for semantic validation in JSON Schema. |
I oppose requiring As noted, I also think it is not a good idea to expose internal implementation details such as UUID format in an API definition. |
I don't require As you pointed out above the concept of an "id" is a role and not a format. So we should introduce this new concept in a new, specific way and not mix it up with Could it be that your concept of an "id" is related to the concept of a "primary key"? See #587 |
What you expect to gain by formally supporting more formats? I realize the format could play a role in code generation, mock data generation, validation and potentially more so I figured I'd ask. I also ask because while writing Swagger tooling in the past, custom formats were easy to support without OpenAPI/Swagger being involved, especially since OpenAPI/Swagger does not dictate or limit which formats you can/cannot use. Here are a few examples of Node.js code registering custom JSON Schema formats for various reasons:
|
Thanks, @ralfhandl for confirming -- makes sense for To answer your second question, an "Your storage model is not your object model is not your resource model is not your representation model." |
👍 |
@whitlockjc Code generation, mock data generation, validation, easier use of tools that know these formats out-of-the-box, better interoperability due to common agreement on what is e.g. a There seems to be demand for more pre-defined formats, see #358, #359, #606, and https://github.com/json-schema/json-schema/wiki/%22format%22-suggestions. |
We are currently using |
@ePaul We came up with the same solution for numeric values with decimal mantissa when mapping primitive types to JSON Schema types and formats. If we can find a third person who did this, it's a pattern :-) We also intended to add a Is that something that you'd also find useful? |
Some of our customers needed decimal format for specifying monetary values. Hence we ended up supporting format decimal in our project AutoRest. |
I think we're in agreement that there are many people using many formats outside of the documented ones. The question is whether this belongs in the OpenAPI specification as some sort of "formal support" or whether this is a tooling problem. It could very well be both. I will tag this appropriately so we can discuss. |
For code generation we need well defined formats. Since swagger spec defines the REST API, it becomes a contract that server and client need to abide by. It is always nice if your contract is explicit about everything. Just making an analogy to make my point: |
It seems that type: string
format: uuid may fall back to String if UUID is not supported. But you cannot invent a type. If that's not the mentality, then we must constrain all formats to a fixed set, which may be hard to support inside the OAI. |
Code generation, as is validation, are tools to me and do not necessarily need OpenAPI changes for reasons I mentioned above. But one thing I just thought of that could make supporting this make sense would be where the OpenAPI wanted to dictate a minimum set of formats all tools must support. I could see that being useful. |
@whitlockjc yes, and with a fallback to primitive types, if not supported. I don't think we should be inventing types. In general, if we specify a format, we should dictate exactly what that is supposed to be. If a user expects a different behavior from a defined format, well, that violates the spec. So... to make this concrete: type: string
format: uuid Should have a very specific format defined in the spec, specifically what @DavidBiesack mentioned:
type: string
format: date-time quite specifically says If I want to invent |
@ralfhandl what about instances where one wants to specify not the precision, which is equivalent to the number of significant digits (correct?), but one wants to specify the scale, or the number of digits following the decimal point. I believe the scale is more appropriate for fixed-point arithmetic and the precision is more appropriate for arbitrary-precision arithmetic. Sanity check, does any of this make sense? |
@mspiegel This absolutely makes sense to me, a complete description of a decimal data type needs two facets:
This covers the SQL data type I'd love to have both |
Tackling PR: #741 |
I think |
Closing this in favor of #845. |
The spec text is normative, except for the examples.
|
As there are several issues proposing new formats, here a list of the possible future full picture
integer
uint8
integer
int8
integer
int16
integer
int32
integer
int64
integer
number
float
number
double
number
decimal
number
string
string
byte
string
base64url
string
binary
boolean
string
date
full-date
- RFC3339string
date-time
date-time
- RFC3339string
time
partial-time
- RFC3339 - #358string
duration
xs:dayTimeDuration
- XML Schema 1.1 - #359string
uuid
string
password
2023-03-24: all of the above-mentioned formats are now registered in the OpenAPI Initiative Formats Registry.
The text was updated successfully, but these errors were encountered: