no-invalid-media-type-examples

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

OAS Compatibility
2.0
3.0
3.1
components
NamedExample
root
PathMap
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

Option Type Description
severity string Possible values: off, warn, error. Default warn.
disallowAdditionalProperties boolean Determines if additional properties are allowed in examples. Default true.

An example configuration:

Copy
Copied
styleguide:
  rules:
    no-invalid-media-type-examples:
      severity: error
      disallowAdditionalProperties: true

Examples

Given this configuration:

Copy
Copied
styleguide:
  rules:
    no-invalid-media-type-examples:
      severity: error
      disallowAdditionalProperties: true

Example of an incorrect media type example:

Copy
Copied
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:

Copy
Copied
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:

Copy
Copied
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

Related rules

Resources