Last updated

no-invalid-media-type-examples

Disallow invalid media type examples by ensuring they comply with the corresponding schema definitions.

OASCompatibility
2.0❌
3.0✅
3.1✅
components
NamedExample
root
Paths
PathItem
Operation
MediaType
Example
Examples

API design principles

"Got examples?" (One of the great advertising campaigns of the 1990s... or was that got milk?)

In any case, those examples should be valid if someone tries them out. However, what are the odds they are valid if they clash with the schema defined? Very little. Most likely there is either a mistake with the example or the schema (or both).

Trust us. It's much nicer to get this alert from Redocly before you ship than from your biggest customer three months later.

Configuration

OptionTypeDescription
severitystringPossible values: off, warn, error. Default warn.
allowAdditionalPropertiesbooleanDetermines if additional properties are allowed in examples. Default false.

An example configuration:

rules:
  no-invalid-media-type-examples:
    severity: error
    allowAdditionalProperties: false

Examples

Given this configuration:

rules:
  no-invalid-media-type-examples:
    severity: error
    allowAdditionalProperties: false

Example of an incorrect media type example:

post:
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            make:
              type: string
            model:
              type: string
            year:
              type: integer
        examples:
          tesla:
            summary: Red Tesla
            value:
              make: Tesla
              model: Y
              year: '2022'

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

Example of a correct media type example:

post:
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            make:
              type: string
            model:
              type: string
            year:
              type: integer
        examples:
          tesla:
            summary: Red Tesla
            value:
              make: Tesla
              model: Y
              year: 2022

Example of incorrect media type example due to additional property:

post:
  requestBody:
    content:
      application/json:
        schema:
          type: object
          properties:
            make:
              type: string
            model:
              type: string
            year:
              type: integer
        examples:
          tesla:
            summary: Red Tesla
            value:
              make: Tesla
              model: Y
              year: 2022
              color: red

Resources

 
Next page