Object Type parameter for OAS media type

[handrews]

It is common practice (particularly in OAS 2.0 and 3.0) to create documents that consist of a referenceable OAS Object (meaning any capitalized-in-the-spec Object type that either has an entry in the Components Object (3.0, 3.1) or is a 3.0 Path Item Object (it is referenceable but in that version did not have a Components Object section), or if 2.0 is covered any of the five different Definitions Objects.

If we want these to be able to have media types, then we probably need to support an object-type or similar Media Type parameter. While 3.1 added the ability to wrap re-usable components in complete documents without having to define API paths, this sort of split remains supported and in common use.

I don't know if we want to add this complexity, but it's a significant use case. It also introduces the corner case that a JSON Schema document could alternatively have a media type like application/openapi+yaml;object-type=Schema, which would be useful if the OpenAPI media types are ready for standardization before the JSON Schema media types.

[ioggstream]

Good catch! I think:

• I will sketch a PR for that;
• I'll leave OAS 2.0 out of scope for this document.

[handrews]

@ioggstream yeah leaving out 2.0 is probably for the best. With 3.0.4 and 3.1.1 we've substantially clarified how parsing and referencing work (it's a bit different in 3.0.x and 3.1.x — 3.1.x separates identity and location, 3.0.x doesn't), but we won't be re-visiting 2.0.

[ioggstream]

@handrews what's the expected behavior here?

• hypothesis 1

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

< HTTP/1.1 200 OK
< Content-Type: application/openapi+yaml;version=3.0;component=Schema
<
< Surname:
<   type: string
<   example: Rossi

• hypothesis 2

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

< HTTP/1.1 200 OK
< Content-Type: application/openapi+yaml;version=3.0;component=Schema
<
< type: string
< example: Rossi

[handrews]

I might debate component vs object but both are arguably correct (the first referencing the Components Object and the second referencing general Object terminology.

Hmm... I might have resolved my own bikeshedding, as "Object" includes non-referenceable Objects, but Components are always referenceable. So I agree that component is probably better than object.

Thinking more, someone might think that component gets them a specific component by name, as that is one of several ways in which you can connect to a component. In 4.0, we might move to "referencing" by component name rather than JSON Pointer fragment, so this could be an important distinction in the future.

So it might better to use componentType or just type (sigh... it's so overloaded, I know... I was using otype at one point but it's rather cryptic) to distinguish between types of components and individual components. 🤔

[ioggstream]

I was guessing whether the usage of the new parameter is ok in the request/response.

We can bikeshed the name later on. I just wanted to avoid overloaded names like type/object for now, since I initially confused object-type with the JSON Schema type: object ;)

[darrelmiller]

I don't think that creating a mechanism to formalize the existence of fragments of OpenAPI documents is a good idea. OAS 3.1.1 has formalized how to interpret pointing at JSON/YAML documents. Most people who create partial OpenAPI documents refer to them with relative file paths and therefore wouldn't be able to communicate a media type anyway.
I think we are adding unnecessary complexity by creating this additional parameter.

[handrews]

@darrelmiller that works for me. It will make it more obvious that the document-fragment pattern is discouraged.