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.
| Place | example | examples |
|---|---|---|
| Media type (a request or response body), parameter, header | one value | a map of named Example Objects: a value (or an externalValue pointing to a file), with an optional summary and description |
| Schema, OpenAPI 3.0 | one value | not available |
| Schema, OpenAPI 3.1 | one value, deprecated | a 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:
exampleon the media type. - Several cases a reader should see (a dog and a cat, a success and an edge case):
exampleson the media type, with asummaryeach. - A value that belongs to the type itself (the format of an id): the schema, as
examples: [...]in 3.1 orexample:in 3.0.