schema-example-defined

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.

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.

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

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.rules has the details.

commands:
  lint:
    rules:
      schema-example-defined: off
Was this helpful?