`primaryData` attribute in Media Type Object

[K-Adam]

Media Type Object should have an optional primaryData attribute, to specify the name of the property, where the primary data is located in the schema.

It is very common to return the response object wrapped in a top level property. This way, it is possible to provide additional metadata as well. Example:

responses:
  '200':
    description: successful operation
    content:
      application/json:
        schema:
          type: object
          properties:
            data:
              $ref: '#/components/schemas/User'
            meta:
              $ref: '#/components/schemas/Metadata'
          required: ['data']
        primaryData: data

The OpenApi tools could better understand these type of responses. It would be possible to express, that the data attribute is not really part of any schemas/objects. It is just a wrapper.

The SDK Generators could benefit from this primaryData attribute as well. At the moment, these kind of responses usually have to be manually unwrapped.

[hkosova]

Related: #519, #555, #957, #1749

[handrews]

Envelopes can be implemented in OAS 3.0 using dynamic references. The value of $dynamicAnchor could be chosen to indicate the primary-ness (or you could just use a custom annotation, since JSON Schema wouldn't need to do anything with it).

Would that address your use case?

[K-Adam]

That seems to be a really useful feature, but I'm not sure that it would solve the original issue.
Adding something like primaryData to the spec would standardise this behaviour, so SDK generators could expect it and handle these structures more conviniently.

[handrews]

@K-Adam I'm a bit reluctant to "standardize" something about message bodies outside of media types. #3771 proposes an extensible registry of media type models.

Given that, you could define a vendor- or personal-tree media type (e.g. application/vnd.whoever.envelope+json) that indicates how the envelope works. Perhaps with a media type parameter giving a JSON Pointer to the content.

I realize it's not as clean of a solution as another field, but it might be easier to get done. If an experimental media type such as this takes off, then adding support directly to the OAS would be a lot easier to sell. I suppose one could also experiment with an x- field that does what you're asking for and see if that gets uptake as well.