example : Any

example

Any

Declares a single example of an instance that this schema describes, superseded by the examples keyword.

Value	This keyword must be set to any value Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Other
Applies To	Any
Base Dialect	2020-12
Changed In	None
Introduced In	OpenAPI 3.1
Vocabulary	OpenAPI 3.1
Specification	https://spec.openapis.org/oas/v3.1.2.html#schema-example
Metaschema	https://spec.openapis.org/oas/3.1/meta/base
Official Tests	None
Default	None
Annotation	None
Affected By	None
Affects	None
Also See	example (Vocabulary: OpenAPI 3.2) examples (Vocabulary: Meta Data) default (Vocabulary: Meta Data) deprecated (Vocabulary: Meta Data)

The example keyword declares a single example instance for the schema it occurs in, typically for documentation purposes. This keyword does not affect validation and is not an annotation.

Best Practice

Use the examples keyword instead. The OpenAPI Specification deprecates this one and describes it as retained purely for compatibility with older versions of the OpenAPI Specification.

Digging Deeper

This keyword exists for historical reasons. The OpenAPI 3.0 Schema Object was based on Draft 4, which had no way of declaring examples, as the examples keyword only arrived in Draft 6. OpenAPI 3.0 therefore defined one of its own.

OpenAPI 3.1 re-based the Schema Object on 2020-12. The Meta-Data vocabulary of that dialect defines examples, and this same release deprecated the keyword documented here.

Common Pitfall

Do not confuse this keyword with the example and examples properties that the Parameter, Header, and Media Type Objects declare. Those are properties of an OpenAPI document rather than JSON Schema keywords. Where both are present, the specification has them override this keyword.

Examples

A schema that constrains string instances and declares an example Schema

{
  "$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
  "type": "string",
  "example": "John Doe"
}

Valid A string value is valid, and the declared example plays no part in the outcome Instance

"Jane Doe"

Invalid A non-string value is invalid Instance

A schema that declares an example contradicting its own constraints Schema

{
  "$schema": "https://spec.openapis.org/oas/3.1/dialect/base",
  "type": "string",
  "example": 42
}

Valid A string value is valid, as this keyword is never evaluated against the instance Instance

"Jane Doe"

Looking to master JSON Schema for OpenAPI?