Response Object with optional empty response via content negotiation.

[danielknell]

How would I model a Response Object where one of the content options is an empty response when all keys have to be a media type or media type range and there isn't a media type for empy responses?

My API uses RFC7240 Prefer headers, specifically return=minimal or return=representation to allow the client to request either an empty response or the resources full representation on some endpoints depending on its own requirements.

this would result in say a POST endpoint for a collection path where either of the following are possible:

POST /foo
content-type: application/json
prefer: return=minimal

{"foo": "bar"}


HTTP/1.1 201
preference-applied: return=minimal
location: http://example.com/foo/123

or

POST /foo
content-type: application/json
prefer: return=representation

{"foo": "bar"}


HTTP/1.1 201
preference-applied: return=minimal
location: http://example.com/foo/123
content-type: application/json

{"foo": "bar"}

The closest i can get is the following:

...
post:
  parameters:
    - name: prefer
      in: header
      required: false
      schema:
        type: string
        enum: [ "return=minimal", "return=representation" ]
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            foo:
              type: str
    required: true
  responses:
    "201":
      headers:
        location:
          schema:
            type: string
            format: uri
        preference-applied:
          schema:
            type: string
            enum: [ "return=minimal", "return=representation" ]
      content:
        application/json:
          schema:
            type: object
            properties:
              foo:
                type: str
...

but that implies that the return=minimal response returns the JSON body, is there an established value for the content key for "no media type"?

and further, is there any way to tie the Preference-Applied header values to the individual responses to document it as a discriminator between the different responses?

[karenetheridge]

This is not an answer to your question, but rather an observation for the purpose of addressing this problem in the future: the problem is that for requests, "requestBody" is split out as a property of its own, allowing "required":false to be used when it is relevant, but there is nowhere to specify that a response body is optional because its "content" property is at the same level as the response headers. One possible solution is to add a "responseBody" underneath, which could have a "required" property, adjacent to "content".

---

As a potential stopgap solution, you could perhaps do this:

...
  responses:
    "201":
      headers:
        ...
      content:
        application/json:
          description: "used for prefer: return=representation"
          schema:
            type: object
            properties:
              foo:
                type: str
        */*:
          description: "no response body is returned for prefer: return=minimal"
          schema: false

[danielknell]

I thought about that, but technically its saying any mimetype except JSON is supported without a schema, which would cover things like image/png or application/pdf which dont normally have a schema. Which might confuse clients that are using the spec?

[handrews]

@danielknell those media types can basically have either of two schemas: the boolean schemas false (nothing is allowed) or true (or {}, everything is allowed). JSON Schema draft 2020-12 specifically allows applying schemas to data outside of the JSON data model, it's just that the keywords are generally meaningless for such data. But tools should handle boolean schemas (or their equivalent such as {}) for anything.

[danielknell]

im guessing I would have to set jsonSchemaDialect to https://json-schema.org/draft/2020-12/schema as well as I cant set $schema directly on a boolean schema?

[karenetheridge]

The default jsonSchemaDialect for 3.1+ is https://json-schema.org/draft/2020-12/schema. For 3.0.x and lower, the dialect cannot be changed and the root schema cannot be false, but "not":{} is available as a way to express the false value.

[handrews]

Technically the default dialect is draft 2020-12 plus the OAS extension vocabulary (e.g. discriminator, xml, and the deprecated singular form example), but yes, you do not need to set anything for this to work.

Also, if you ever do need to add an $id and $schema, the schema {} is equivalent to true and there are many equivalents to false, with {"not": {}} being the most clear, so you can add them to those.

[jeremyfiel]

RFC7240 4.2 suggests using a 204 No Content response when a minimal preference is an empty representation. It also allows 200 or other appropriate codes but does not define the representation shape.

Thus, a solution may be to use both codes

POST /foo HTTP/1.1
prefer: return=minimal

{ "foo": "bar" }


HTTP/1.1 204 No Content
preference-applied: return=minimal
location: uri
link: <uri>; rel="self"

POST /foo HTTP/1.1
prefer: return=representation 

{ "foo": "bar" }


HTTP/1.1 201 Created
preference-applied: return=representation
location: uri
link: <uri>; rel="self"

{ "foo": "bar" }

openapi: 3.2.0
info:
  title: blah
  version: V1
paths:
  '/things':
    post:
      responses:
        '201':
          description: Created
          headers:
            preference-applied:
              schema:
                type: string  // this could be more than just minimal or representation so it's open-ended. 
          content:
            'application/json':
              schema:
                type: object
                properties:
                  foo:
                    type: string
              examples:
                representation:
                  value:
                    foo: bar
        '204':
          description: No Content
          headers:
            preference-applied:
              schema:
                enum:
                - 'return="minimal"'
          content:
            'application/json':
              schema: false