Arazzo Media Types

[ioggstream]

I Expect

• Arazzo Media Types ;)

Notes

@darrelmiller @handrews does it make sense?

[handrews]

If we're doing Arazzo, we should also do Overlays. And we should do both.

[handrews]

@ioggstream @darrelmiller I wonder if we should have distinct media types, requiring a new registration of each type, or if we should treat the specification, as well as the version, as a parameter of the more general OpenAPI media type. Or even a profile, although I suspect that's abusing the concept of "profile" a bit.

• application/openapi+json; version=3.2 # The specification parameter defaults to OAS
• application/openapi+json; specification=OAS; version=3.2 # same as previous
• application/openapi+json; specification=Arazzo; version=1.0
• application/openapi+json; specification=Arazzo # currently same as previous as only 1.0.0 and 1.0.1 exist
• application/openapi+json; specification=Overlay

etc.

[handrews]

I suppose alternatively, application/openapi+json without a specifiction or version parameter could mean "I know this is some sort of OpenAPI document, but I'm not sure what and don't care."

We have started talking about having a Manifest for sets of OAS/Arazzo/Overlay documents intended to work together, so a use case for this could be iterating over the manifest and fetching everything while deferring identification of the contents to the parser as the formats are not ambiguous (assuming we stick with #110's decision to disallow fragmentary documents (without an OpenAPI / Arazzo / Overlay object at the root) and treat JSON Schema documents as JSON Schemas.

[ioggstream]

@handrews different media types ease content negotiation.

Having to accommodate all possibilities in a conflated media type will be too complex.
Let's gather some requirements for the arazzo media type in this issue: we can even defer to a new doc :D

[handrews]

@ioggstream in one PR you're arguing to conflate all Objects into one media type, which is ambiguous and extremely complex, but here you're arguing against conflating multiple specifications, which are few in number and are never ambiguous?

[ioggstream]

in one PR you're arguing to conflate all Objects into one media type.

While I think the approach depends on the context, I'll summarize the rationale here:

• this will make "specification" a mandatory parameter, so it will end with 2 mandatory parameters;
• Objects are defined in the same spec, have all the same version, and each OAS implementation will probably support all Objects.
• Arazzo is in another document, with its own version and (probably) has its own parser, so it probably deserves it's own separate media type.

OT: wrt #131 and #121, I made a proposal going towards "OpenAPI Object only" that preserves content negotiation, but please let's only discuss that topic there :D