standard-media-types

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

This rule checks that the media types of request bodies, responses, parameters and headers are ones the rule knows: a top-level type registered with IANA (application, text, image, multipart, …) and one of about sixty common subtypes (json, xml, problem+json, vnd.api+json, form-data, x-www-form-urlencoded, octet-stream, pdf, png, …), or * for either. The known subtypes include those of the sequential media types that OpenAPI 3.2 describes with itemSchema: event-stream, jsonl, x-ndjson, json-seq, geo+json-seq and mixed.

Rule details

A media type that no client library knows is parsed by hand on both sides; a misspelled one (application/jsn) is a body nobody parses at all. The common types have parsers everywhere.

The rule reports Non-standard media type is used (...) on the object that declares the media type. Vendor types of your own, application/vnd.acme.v1+json, are reported too: turn the rule off when the API uses them on purpose.

Examples

Good.

paths:
  /users:
    get:
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/User"

Bad. application/x-custom is a type the rule does not know.

paths:
  /users:
    get:
      responses:
        "200":
          description: OK
          content:
            application/x-custom:
              schema:
                $ref: "#/components/schemas/User"

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.rules has the details.

commands:
  lint:
    rules:
      standard-media-types: off
Last updated on View as Markdown
Was this helpful?