OAS 3.1: Suggest rephrasing data-types section for format keyword and primitive types.

[sebastien-rosset]

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.

[MikeRalphson]

This sounds like a good catch. Could you work up a PR?

[sebastien-rosset]

This sounds like a good catch. Could you work up a PR?

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.

Primitives have an optional modifier property: format, which is defined by JSON Schema. OAS uses several known additional formats to define in fine detail the data type being used. However, to support documentation needs, the format property is an open string-valued property, and can have any value. Additional formats MAY be used even though undefined by either JSON Schema or this specification. Types that are not accompanied by a format property follow the type definition in the JSON Schema. Tools that do not recognize a specific format MAY default back to the type alone, as if the format is not specified.

Update: never mind, scratch that, I see there are additional format.

[sebastien-rosset]

This sounds like a good catch. Could you work up a PR?

I have opened #2302

[MikeRalphson]

I agree, I don't think that paragraph is now adding anything.

[sebastien-rosset]

I agree, I don't think that paragraph is now adding anything.

I've removed a few sentences while trying to keep the flow for the new data formats being introduced.

[sebastien-rosset]

@MikeRalphson, is there anything I should do as a next step?

[MikeRalphson]

No, I've labelled the PR for review, hopefully we will get to it on tomorrow's TSC call.

[MikeRalphson]

Closing as #2302 was merged. Thanks.