# schema-format-type-mismatch

Source: https://api-genie.dev/docs/linter/openapi/rules/schema-format-type-mismatch

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. Fixed by `--fix`. In the rulesets: Recommended at error, Strict at error, All at error.

This rule checks that the `format` of a schema fits its `type`: `date` on a string, `int64` on an
integer.

## Rule details

A format that does not fit the type is a contradiction that every tool resolves its own way: a
validator trusts the type and ignores the format, a generator may do the opposite, and a mock
server generates data that the API cannot return. The rule reports a schema whose `format` is in
the
[OpenAPI format registry](https://spec.openapis.org/registry/format/) when none
of the schema's types is a JSON type of that format (see
[Formats](/docs/reference/cli/formats) for the list). For example:

- `date`, `uuid`, `email`, `http-date`, `language` and the other string
  formats need `type: string`;
- `int8` to `uint64`, `int32`, `int64`, `double-int` and `sf-integer` need
  `type: integer` or `type: number`;
- `float`, `double` and `sf-decimal` need `type: number` (not `integer`);
- `int64` and `uint64` also allow `type: string`, and `decimal` and
  `decimal128` allow `string` and `number`, as the registry does;
- `unixtime` allows `integer`, `number` and `string`.

The formats of `openapi.custom_formats` in the
[configuration file](/docs/reference/cli/configuration) are checked against
the type given there, and override the registry's.

A schema without a `type` is reported too. Formats neither in the registry nor
custom are left to [schema-format-unknown](/docs/linter/openapi/rules/schema-format-unknown).

## Configuration

An object with one optional property, `fixTypeFromFormat`: whether `--fix` replaces a mismatched
type with the type of the format. `true` by default.

## Examples

**Good**. `date` is a string format.

```yaml
components:
  schemas:
    User:
      type: object
      properties:
        birthDate:
          type: string
          format: date
```

**Bad**. An integer with a string format.

```yaml
components:
  schemas:
    User:
      type: object
      properties:
        birthDate:
          type: integer
          format: date
```

## Automatic fixes

`--fix` gives the schema the type of its format: integer formats set `integer`, `decimal` and
`decimal128` set `string`, the other number formats set `number` and string formats set `string`.
Unknown formats stay for you to resolve.
