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:

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

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/

respones:
  content:
    'application/json;profile=urn:yourdomain:short':
       schema:
          $ref: '#/components/schemas/shortResponseSchema'
    'application/json;profile=urn:yourdomain:long':
       schema:
          $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?