What is the JSON syntax to use "oneOf" to describe alternate schemas

In our system we would like to use a path parameter for our GET ( /category/{format} ) to provide one of two response schemas, one where the format value is “summary”, and a more extensive response if the format parameter is “verbose”.

From the OpenAPI docs for version 3 it seems this is permitted by using the “oneOf” section but it is unclear to me exactly what the JSON syntax for this usage.

Can someone please provide a simple example for this use case?

I’ll provide a direct answer to your query, then a suggestion for what may be a better solution.

If your response references the schema ‘myResponse’ for your application/json , you can use this syntax:

      title: My Response
      description: A short or long response
        - '#/components/schemas/shortResponseSchema'
        - '#/components/schemas/longResponseSchema'
      title: Short Response
      description: A shorter response
      title: Long Response
      description: A longer response
        - '#/components/schemas/shortResponseSchema'
        - type: object

This is a literal interpretation of your question.

However, many tools (like client code generators) do not
handle oneOf very well.

Another option is to not us a query parameter, but rather use
a profile in the Accept: request header media type
and a profile in the response. See https://www.w3.org/TR/dx-prof-conneg/

          $ref: '#/components/schemas/shortResponseSchema'
          $ref '#/components/schemas/longResponseSchema'

then the client can make the request and use

Accept: application/json;profile=urn:yourdomain:short

to ask for the shorter response, and

Accept: application/json;profile=urn:yourdomain:long

to ask for the longer response, using standard HTTP content type negotiation.

I like your approach to using media type profiles, but I am curious, what aspects of the design space lead you to prefer this approach?