schema-format-deprecated

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

This rule reports the formats which the OpenAPI format registry marks as deprecated, and names what replaces them.

Rule details

From OpenAPI 3.1, schemas are JSON Schema 2020-12, which describes encoded content with contentEncoding and contentMediaType. The registry deprecates the formats that said the same thing in OpenAPI 3.0:

Format Use instead
byte contentEncoding: base64
base64url contentEncoding: base64url
binary contentMediaType, or the media type of the body or part without a schema

OpenAPI 3.0 has neither keyword, so in 3.0 documents the rule reports these formats as hints: they show where the document will need a change when it moves to OpenAPI 3.1, without counting as warnings or failing the run. See Formats for every format and what API Genie does with it. Keep the formats, and turn the rule off, when the document must stay readable by tools that only understand the OpenAPI 3.0 formats.

Examples

Good. The encoding and the media type as keywords.

openapi: 3.1.0
components:
  schemas:
    Avatar:
      type: string
      contentEncoding: base64
      contentMediaType: image/png

Bad. byte in a 3.1 document.

openapi: 3.1.0
components:
  schemas:
    Avatar:
      type: string
      format: byte

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:
      schema-format-deprecated: off

Related rules

Further reading

Was this helpful?