schema-example-defined
Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error
This rule ensures that top-level schemas of an AsyncAPI document provide examples.
Rule details
Examples make schemas easier to understand, and are used by documentation generators, mock servers and test tools to produce realistic messages.
The schema-example-defined rule checks top-level schemas only; nested
schemas (such as properties or array items) are not checked. Top-level
schemas are:
- the entries of
components/schemas(references are skipped). The rule reportsSchema does not define examplesfor these. - inline message payloads, i.e. payloads that are not references. The rule
reports
Message payload schema does not define examplesfor these. Referenced payloads are checked as component schemas.
A schema counts as having examples when it has a non-empty examples list,
when it has a const value, or when it is a boolean schema (true or
false). In addition, a message whose examples list contains at least one
example with a payload counts as providing examples for its inline payload.
Turn the rule off if your documentation and tooling do not use examples.
Examples
Good. The component schema has its own examples, and the inline payload is illustrated by a message example.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
messages:
petAdopted:
payload:
type: object
properties:
name:
type: string
examples:
- payload:
name: Rex
components:
schemas:
PetStatus:
type: string
enum: [AVAILABLE, ADOPTED]
examples: [AVAILABLE]
Bad. Neither the component schema nor the inline payload provide examples.
asyncapi: 3.0.0
info:
title: Pet Events
version: 1.0.0
channels:
petAdopted:
address: pets.adopted
messages:
petAdopted:
payload:
type: object
properties:
name:
type: string
components:
schemas:
PetStatus:
type: string
enum: [AVAILABLE, ADOPTED]
Turn it off or change its severity
In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.asyncapi has the details.
commands:
lint:
asyncapi:
rules:
schema-example-defined: off