schema-format-deprecated

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.

Configuration

None.

Examples

Good.

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

Bad.

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

When Not to Use It

When the document must stay readable by tools that only understand the OpenAPI 3.0 formats.

Compatibility

OpenAPI 3.1 and 3.2 documents get warnings; OpenAPI 3.0 documents get hints.