spectral:oas warn on by default

oas3-examples-value-or-externalValue

Examples must have either "value" or "externalValue" field.

Applies to
examples
Selects
$.components.examples[*]
$.paths[*][*]..content[*].examples[*]
$.paths[*][*]..parameters[*].examples[*]
$.components.parameters[*].examples[*]
$.paths[*][*]..headers[*].examples[*]
$.components.headers[*].examples[*]
Function
xor
Specs
OpenAPI 3.0OpenAPI 3.1OpenAPI 3.2

Use it

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

extends: spectral:oas
rules:
  oas3-examples-value-or-externalValue: warn   # or off, or another severity

Definition

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

oas3-examples-value-or-externalValue:
  description: Examples must have either "value" or "externalValue" field.
  recommended: true
  formats:
    - OpenAPI 3.x
  given:
    - '$.components.examples[*]'
    - '$.paths[*][*]..content[*].examples[*]'
    - '$.paths[*][*]..parameters[*].examples[*]'
    - '$.components.parameters[*].examples[*]'
    - '$.paths[*][*]..headers[*].examples[*]'
    - '$.components.headers[*].examples[*]'
  then:
    function: xor
    functionOptions:
      properties:
        - externalValue
        - value

About this rule

Examples for requestBody or response examples can have an externalValue or a value, but they cannot have both.

Bad Example

paths:
  /pet:
    put:
      operationId: "replace-pet"
      requestBody:
        content:
          "application/json":
            examples:
              foo:
                summary: A foo example
                value: { "foo": "bar" }
                externalValue: "http://example.org/foo.json"
                # marp! no, can only have one or the other

Sources