Skip to content

Commit 393ab02

Browse files
char0nhandrews
authored andcommitted
Editorial change: Include Header Object into 'Working With Examples' section
1 parent dc94d95 commit 393ab02

File tree

1 file changed

+5
-5
lines changed

1 file changed

+5
-5
lines changed

src/oas.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2598,19 +2598,19 @@ Tooling implementations MAY choose to validate compatibility automatically, and
25982598

25992599
##### Working with Examples
26002600

2601-
Example Objects can be used in both [Parameter Objects](#parameter-object) and [Media Type Objects](#media-type-object).
2601+
Example Objects can be used in [Parameter Objects](#parameter-object), [Header Objects](#header-object) and [Media Type Objects](#media-type-object).
26022602
In both Objects, this is done through the `examples` (plural) field.
2603-
However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in both Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of both Objects.
2603+
However, there are several other ways to provide examples: The `example` (singular) field that is mutually exclusive with `examples` in all three Objects, and two keywords (the deprecated singular `example` and the current plural `examples`, which takes an array of examples) in the [Schema Object](#schema-object) that appears in the `schema` field of all three Objects.
26042604
Each of these fields has slightly different considerations.
26052605

26062606
The Schema Object's fields are used to show example values without regard to how they might be formatted as parameters or within media type representations.
26072607
The `examples` array is part of JSON Schema and is the preferred way to include examples in the Schema Object, while `example` is retained purely for compatibility with older versions of the OpenAPI Specification.
26082608

2609-
The mutually exclusive fields in the Parameter or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation.
2610-
The exact serialization and encoding is determined by various fields in the Parameter Object, or in the Media Type Object's [Encoding Object](#encoding-object).
2609+
The mutually exclusive fields in the Parameter, Header or Media Type Objects are used to show example values which SHOULD both match the schema and be formatted as they would appear as a serialized parameter or within a media type representation.
2610+
The exact serialization and encoding is determined by various fields in the Parameter Object, Header Object, or in the Media Type Object's [Encoding Object](#encoding-object).
26112611
Because examples using these fields represent the final serialized form of the data, they SHALL _override_ any `example` in the corresponding Schema Object.
26122612

2613-
The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.
2613+
The singular `example` field in the Parameter, Header or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.
26142614

26152615
Some examples cannot be represented directly in JSON or YAML.
26162616
For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description.

0 commit comments

Comments
 (0)