# schema-example-defined

Source: https://apigenie.pl/docs/linter/asyncapi/rules/schema-example-defined

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.

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

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