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 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.

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

Related rules

Was this helpful?