no-invalid-parameter-examples

July 16, 2026 · View on GitHub

Disallow invalid parameter examples.

OASCompatibility
2.0✅
3.0✅
3.1✅
3.2✅
flowchart TD

Root ==> Paths --> PathItem --> Operation --> Parameter --> Example
PathItem --> Parameter
Parameter --> Schema
Root ==> components

NamedParameters --> Parameter

Schema -.compares schema\nto example.- Example

subgraph components
NamedParameters
end


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

API design principles

If your parameter schema and example conflict, there is a problem in the definition of the schema or the example. Solve it before you ship it.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default warn.
allowAdditionalPropertiesbooleanDetermines if additional properties are allowed in examples. Default false.
rules:
  no-invalid-parameter-examples:
    severity: error
    allowAdditionalProperties: false

Examples

Given the following configuration:

rules:
  no-invalid-parameter-examples:
    severity: error
    allowAdditionalProperties: false

Example of incorrect parameter example:

paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: username
          in: query
          schema:
            type: string
            maxLength: 15
          description: Value to query the chess results against usernames
          example: ThisUsernameIsTooLong

Example of correct parameter example:

paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: username
          in: query
          schema:
            type: string
            maxLength: 10
          description: Value to query the chess results against usernames
          example: ella

OpenAPI 3.2 dataValue

In OpenAPI 3.2, provide the structured example in dataValue, which is validated against the schema the same way value is. When dataValue is present, value must be absent (see spec-example-values).

Example of an incorrect dataValue:

paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: rating
          in: query
          schema:
            type: integer
          examples:
            grandmaster:
              dataValue: '2500'

This example produces an error because the rating is a string instead of an integer.

Example of a correct dataValue:

paths:
  /results:
    get:
      summary: Search Chess Results
      operationId: searchChessResult
      parameters:
        - name: rating
          in: query
          schema:
            type: integer
          examples:
            grandmaster:
              dataValue: 2500

Resources