# schema-example-defined

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

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: Recommended at warning, Strict at error, All at error.

This rule checks that every schema that is not trivial, an object, an array or a string with a
`pattern`, has an example.

## Rule details

An example shows what a schema describes faster than the schema does, and documentation,
mock servers and generated tests use it in place of a value they would have to make up: a
`pattern` tells the reader less than one string that matches it.

The rule checks the schemas a document names or uses directly: the entries of
`components/schemas` and the inline schemas of media types, parameters and headers. A schema
passes with an `example` or `examples` of its own, and an inline schema also with an `example` or
`examples` of the media type, parameter or header that holds it. A schema combined with `allOf`
counts as an object when one of its parts is. The properties and items of a schema are not
checked on their own, since the example of the schema shows them, and a `$ref` is checked where
its target is defined.

The rule reports `Schema has no example`.

## Examples

**Good**. The example shows a username that matches the pattern.

```yaml
components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          pattern: "^[a-z0-9_-]{3,16}$"
      example:
        username: "john_doe"
```

**Bad**. The reader works out a valid username from the pattern.

```yaml
components:
  schemas:
    User:
      type: object
      properties:
        username:
          type: string
          pattern: "^[a-z0-9_-]{3,16}$"
```
