spectral:oas error on by default

oas3-valid-schema-example

Examples must be valid against their defined schema.

Applies to
example
Selects
$.components.schemas..[?(@property !== 'properties' && @ && (@ && @.example !== void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties || @.items))]
$..content..[?(@property !== 'properties' && @ && (@ && @.example !== void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties || @.items))]
$..headers..[?(@property !== 'properties' && @ && (@ && @.example !== void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties || @.items))]
$..parameters..[?(@property !== 'properties' && @ && (@ && @.example !== void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref || @.properties || @.items))]
Function
oasExample
Specs
OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2
Message
{{error}}

Use it

This rule ships with OpenLint in spectral:oas. Extending the ruleset turns it on:

extends: spectral:oas
rules:
  oas3-valid-schema-example: error   # or off, or another severity

Definition

As defined in @openlint/openlint-rulesets. Functions show by name.

oas3-valid-schema-example:
  description: Examples must be valid against their defined schema.
  message: '{{error}}'
  severity: 0
  recommended: true
  formats:
    - OpenAPI 3.x
  given:
    - >-
      $.components.schemas..[?(@property !== 'properties' && @ && (@ &&
      @.example !== void 0 || @.default !== void 0) && (@.enum || @.type ||
      @.format || @.$ref || @.properties || @.items))]
    - >-
      $..content..[?(@property !== 'properties' && @ && (@ && @.example !== void
      0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref ||
      @.properties || @.items))]
    - >-
      $..headers..[?(@property !== 'properties' && @ && (@ && @.example !== void
      0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref ||
      @.properties || @.items))]
    - >-
      $..parameters..[?(@property !== 'properties' && @ && (@ && @.example !==
      void 0 || @.default !== void 0) && (@.enum || @.type || @.format || @.$ref
      || @.properties || @.items))]
  then:
    function: oasExample
    functionOptions:
      schemaField: $
      oasVersion: 3
      type: schema

About this rule

Examples must be valid against their defined schema. This rule is applied to Schema objects.

Good Example

schemas:
  Pet:
    title: Pet
    type: object
    properties:
      id:
        type: integer
        example: 123
      name:
        type: string
        example: Bubbles
      petType:
        type: string
        example: dog
    required:
      - id
      - name
      - petType

Bad Example

This would throw an error since the example value for petType is an integer, not a string.

schemas:
  Pet:
    title: Pet
    type: object
    properties:
      id:
        type: integer
        example: 123
      name:
        type: string
        example: Bubbles
      petType:
        type: string
        example: 123
    required:
      - name
      - petType

Sources