Skip to content

example vs examples in OpenAPI: where each goes and which one tools use

Last checked and updated

example holds one value; examples holds several. What trips people up is that examples has two different forms depending on where it is written, and that the two keywords cannot be combined in one place.

Placeexampleexamples
Media type (a request or response body), parameter, headerone valuea map of named Example Objects: a value (or an externalValue pointing to a file), with an optional summary and description
Schema, OpenAPI 3.0one valuenot available
Schema, OpenAPI 3.1one value, deprecateda list of values (the JSON Schema keyword)

On a media type

responses:
  "200":
    content:
      application/json:
        schema:
          $ref: "#/components/schemas/Pet"
        examples:
          dog:
            summary: A dog
            value: { id: "p1", name: "Rex", kind: "dog" }
          cat:
            summary: A cat
            value: { id: "p2", name: "Tom", kind: "cat" }

Named examples can be shown in documentation as a choice, and a tool can ask for one by name. A single example is shorter:

        example: { id: "p1", name: "Rex", kind: "dog" }

example and examples are mutually exclusive there: write one or the other.

In a schema

Owner:
  type: object
  properties:
    id:
      type: string
      examples: ["o-100"]     # OpenAPI 3.1: a list
    name:
      type: string
      example: Ada            # works in 3.0 and 3.1; deprecated in 3.1

A schema-level example describes the type wherever it is used. A media-type example describes one particular response and wins where both exist.

Which one a mock server answers with

A mock generated from the description above answers with the first named example, and with another when asked:

$ curl http://127.0.0.1:4654/pets/1
{"id":"p1","name":"Rex","kind":"dog"}

$ curl http://127.0.0.1:4654/pets/1 -H 'Prefer: example=cat'
{"id":"p2","name":"Tom","kind":"cat"}

Where the media type has no example, the schema's are used, property by property:

$ curl http://127.0.0.1:4654/owners/1
{"id":"o-100","name":"Ada","age":"forty"}

The order this mock follows is: the media type's example, then the first of its examples, then the schema's example or the first of its examples, then a generated value. Other tools may choose differently when several are present, which is a reason not to scatter conflicting examples over both levels.

Examples are not validated, unless you ask

The last answer contains "age":"forty" for a property declared type: integer. The mock returned the example as written. A linter catches it:

$ apigit lint ex.yaml
  107:20  error  oas3-valid-schema-example  "example" property type must be integer  (components.schemas.Owner.properties.age.example)

An example that contradicts its schema misleads readers and breaks clients tested against the mock, so keep the lint rule on.

Choosing

  • One realistic value per body: example on the media type.
  • Several cases a reader should see (a dog and a cat, a success and an edge case): examples on the media type, with a summary each.
  • A value that belongs to the type itself (the format of an id): the schema, as examples: [...] in 3.1 or example: in 3.0.

Sources

Related pages

Try it with your own API

Create a free workspace, add an OpenAPI file, and publish its documentation and a mock server from the same repository.

Free for individuals. No credit card.

$ npm install -g @apigit/cli$ apigit auth login$ apigit doc publish