Content negotiation when application/openapi+json only applies to OpenAPI Objects

[ioggstream]

Discussion

• Imagine application/openapi+json to only apply to OpenAPI Objects
• How to enable content negotiation of $ref'd resources?

Notes

Start this topic because it seems to me that it is not clear.

In closing #110 we decided not to convey the specific OpenAPI Object associated with the resource.
My understanding was that it was still possible to convey other objects (e.g., Schema Objects)
but let's imagine it's not possible.

How to negotiate the correct version for OAS3.0 vs OAS3.1 Schema Objects
(e.g., requesting a Schema Object to a server that can respond with an OAS 3.0 compatible or with a 3.1/JSON Schema object)?
Note that OAS3.0 Schema Objects are an extension of JSON Schema objects,
but clients may want a resource with that specific extension.

This content-negotiation is key to allow ecosystems based on OAS3.0 to migrate to OAS3.1/JSON Schema,
so that schema servers can reply with the best OAS version.

A client retrieving a Schema from an openapi: 3.0 document can then

Accept: application/openapi+json; version=3.0

[handrews]

@ioggstream Schema Objects as standalone documents are just JSON Schema documents. They are application/schema+json or application/jsonschema+json or whatever the media type ends up being.

• OpenAPI Object at the root: application/openapi+json
• Schema Object at the root: application/schema+json
• some other Object e.g. Path Item Object at the root: no media type defined

Note that OAS3.0 Schema Objects are an extension of JSON Schema objects.

This is irrelevant for the purpose of the media type, as JSON Schema allows extensions and silently ignores any that it does not understand. Presumably, an application consuming a JSON Schema document in the context of a reference expecting an OAS 3.0 Schema Object will handle extensions accordingly. This falls under JSON Schema draft-04's language to the effect that extensions are handled by out-of-band agreements between producers and consumers of schemas (in draft 2020-12 and OAS 3.1, it is handled by OAS-specific metaschemas and vocabularies, but that is not how draft-04 worked).

[ioggstream]

@handrews

Schema Objects as standalone documents are just JSON Schema documents

As of now, there is no way to Accept for an OAS3.0 schema. We could probably
define a prosaic way of interpreting the media type in the Accept

🐹 🛞 will PR soon

[...] This is irrelevant for the purpose of the media type,
[...] an application consuming a JSON Schema document
in the context of a reference expecting an OAS 3.0 Schema Object will handle extensions accordingly

The goal of this document is to allow content negotiation,
and allow clients to express a preference for a specific version of OAS.

Imagine the following use case:

1. As an API Consumer
2. I want to load an API specification
3. compatible with my capability (e.g., OAS3.0)
4. from an API Catalog with various capabilities (OAS3.0, OAS3.2)

I start by retrieving an OAS 3.0

> GET /openapi.yaml
> Accept: application/openapi+yaml; version=3.0

< HTTP/1.1 200 OK
< Content-Type: application/openapi+yaml; version=3.0
<
< openapi: 3.0.4
< ...
< components:
<   schemas:
<     Foo: { $ref: "/foo.yaml" }

The client then retrieves /foo.yaml, but it wants the OAS3.0 version, not the OAS3.2

> GET /foo.yaml
> Accept: application/openapi+yaml; version=3.0

< HTTP/1.1 200 OK
< Content-Type: application/yaml
<
< type: string
< enum: [ it, en ]

[handrews]

@ioggstream We cannot have both OpenAPI Object-rooted documents and JSON Schema documents be application/openapi+* with just a version parameter.

The options are:

• Add an object parameter as I suggested in Object Type parameter for OAS media type #110, which was rejected.
• Use application/schema+* (or application/jsonschema+*?) with a schema parameter that identifies the appropriate metaschema. Which, admittedly, probably doesn't exist for 3.0 but theoretically could. Of course, content negotiation of JSON Schema resources using the schema parameter has not been thoroughly defined, and needs to address issues like responding with a schema using a later version of the same metaschema, e.g. because a bug in the metaschema was fixed.

But we definitely can't have application/openapi+* returning documents with different root Objects, because that would introduce far too much ambiguity into the system.

[ioggstream]

we definitely can't have application/openapi+* returning documents with different root Objects

OK, I updated the response to return an application/yaml. See #131 (comment)

Makes more sense now?