schema-example-defined

Since 0.9.0

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 reports Schema does not define examples for these.
• inline message payloads, i.e. payloads that are not references. The rule reports Message payload schema does not define examples for 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.

Configuration

None.

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]

When Not to Use It

You may disable this rule if your documentation and tooling do not use examples.

Compatibility

This rule is compatible with AsyncAPI 3.x documents. AsyncAPI 2.x documents are rejected by the reader and are not linted.

Related rules

• schema-constraints