# schema-format-deprecated

Source: https://apigenie.pl/docs/linter/openapi/rules/schema-format-deprecated

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. 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](https://spec.openapis.org/registry/format/) 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](/docs/reference/cli/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.

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

**Bad**. `byte` in a 3.1 document.

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