Repository navigation
OAS 3.1: Suggest rephrasing data-types section for format keyword and primitive types. #2301
Description
The OAS 3.1 data types section states:
Primitives have an optional modifier property: format, which is defined by JSON Schema.
Implied in that sentence is that the format keyword does not apply to non-primitive types. However, In the JSON schema specification section 7, it is stated the format keyword applies to all model instance types:
All format attributes defined in this section apply to strings, but a format attribute can be specified to apply to any instance types defined in the data model defined in the core JSON Schema.
Based on the above the format keyword can apply to null, boolean, object, array, number and string.
One of the goal of OAS 3.1 is to remove some of the constraints that existed in 3.0.3 and support full JSON schema specification. Therefore, shouldn't https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#data-types be rephrased to to avoid conveying the format keyword applies to primitive types? Even if in practice most people use the format keyword for primitive types, the spec doesn't have such restriction.
Activity
MikeRalphson commentedon Aug 1, 2020
This sounds like a good catch. Could you work up a PR?
sebastien-rosset commentedon Aug 1, 2020
sure, will do. In past PRs, my understanding is the guiding principle has been to remove normative sentences from the OAS spec if there is already a normative text in the JSON schema specification. Therefore, I'm wondering if this entire paragraph should be removed? I don't see anything new which isn't already specified in the JSON schema specification.
Update: never mind, scratch that, I see there are additional format.
sebastien-rosset commentedon Aug 1, 2020
I have opened #2302
MikeRalphson commentedon Aug 1, 2020
I agree, I don't think that paragraph is now adding anything.
sebastien-rosset commentedon Aug 1, 2020
I've removed a few sentences while trying to keep the flow for the new data formats being introduced.
sebastien-rosset commentedon Aug 18, 2020
@MikeRalphson, is there anything I should do as a next step?
MikeRalphson commentedon Aug 19, 2020
No, I've labelled the PR for review, hopefully we will get to it on tomorrow's TSC call.
MikeRalphson commentedon Jan 12, 2021
Closing as #2302 was merged. Thanks.