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