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