standard-media-types

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

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, application/octet-stream or the sequential types text/event-stream, application/jsonl, application/x-ndjson, application/json-seq, application/geo+json-seq and multipart/mixed. Wildcards (*/*, application/*) are accepted, and parameters after ; (like charset=utf-8) are ignored. Values without a subtype, like json, are reported.

The OpenAPI and AsyncAPI linters have rules of the same name, standard-media-types and standard-media-types.

Turn the rule off if your API deliberately uses vendor-specific media types that are not on the built-in list.

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

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        standard-media-types: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?