no-example-value-and-externalValue

May 18, 2026 · View on GitHub

Ensures that examples object properties externalValue and value are mutually exclusive.

{% admonition type="warning" name="Deprecated" %} This rule is deprecated in favor of spec-example-values. {% /admonition %}

OASCompatibility
2.0❌
3.0✅
3.1✅
3.2❌
flowchart TD

Root ==> Paths --> PathItem --> Operation --> Parameter --> MediaType
PathItem --> Parameter
Operation --> RequestBody --> MediaType --> Example
Operation --> Responses --> MediaType
NamedExamples --> Example
Root ==> components

subgraph components
NamedExamples
end

style Example fill:#codaf9,stroke:#0044d4,stroke-width:5px

API design principles

According to the OpenAPI specification, the value field and externalValue field are mutually exclusive. An object that contains both violates the specification. The intended use of the value field is to provide in-line example values, while the externalValue field is meant for URIs that reference examples stored outside of the API description file.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default error (in recommended configuration).

An example configuration:

rules:
  no-example-value-and-externalValue: error

Examples

Given this configuration:

rules:
  no-example-value-and-externalValue: error

Example of an incorrect example object:

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: { foo: bar }
          externalValue: https://example.org/examples/foo-example.xml
        bar:
          summary: A bar example
          value: { bar: baz }
          externalValue: https://example.org/examples/bar-example.xml

Example of a correct example object:

requestBody:
  content:
    application/json:
      schema:
        $ref: '#/components/schemas/Address'
      examples:
        foo:
          summary: A foo example
          value: { foo: bar }
        bar:
          summary: A bar example
          externalValue: https://example.org/examples/address-example.xml

Resources