Linter rulesSwagger 2.0standard-media-types

standard-media-types

Since 0.9.0

This rule checks whether a Swagger 2.0 document uses only well-known media types.

Rule Details

Non-standard or misspelled media types lead to interoperability issues: clients and servers may fail to negotiate the format of requests and responses.

The standard-media-types rule checks:

  • the root consumes and produces lists,
  • the consumes and produces lists of every operation,
  • the media type keys of the examples of every response (response references are skipped).

It reports Non-standard media type is used (<media type>) for every value that is not on the built-in list of well-known media types, such as application/json, application/xml, application/x-www-form-urlencoded, multipart/form-data, text/plain or application/octet-stream. Wildcards (*/*, application/*) are accepted, and parameters after ; (like charset=utf-8) are ignored. Values without a subtype, like json, are reported.

Configuration

None.

Examples

Good.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
consumes: [application/json]
produces: [application/json, application/xml]
paths:
  /pets:
    get:
      produces: [text/plain]
      responses:
        '200':
          description: The list of pets.
          examples:
            text/plain: Rex, Fluffy

Bad. application/x-custom and text/foo are not well-known media types, and json has no subtype.

swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
consumes: [application/x-custom]
paths:
  /pets:
    get:
      produces: [json]
      responses:
        '200':
          description: The list of pets.
          examples:
            text/foo: Rex

When Not to Use It

You may disable this rule if your API deliberately uses vendor-specific media types that are not on the built-in list.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x and AsyncAPI documents are linted by the OpenAPI and AsyncAPI linters, which have their own standard-media-types rules.

Related rules

Further reading