# Formats

Source: https://apigenie.pl/techdocs/reference/cli-formats

API Genie follows the [OpenAPI format registry](https://spec.openapis.org/registry/format/),
the list of `format` values the OpenAPI Initiative keeps, with the JSON types each applies to.
The same list drives every part of API Genie (docs/adrs/166):

- **Validation.** [`apigenie-server`](/techdocs/reference/cli-server) checks the formats of
  requests and responses (mock and `--proxy-to`), as do the contract checks of `apigenie test`. A
  format applies to its JSON types only: `format: int32` checks numbers, and leaves a string to
  `type`. `validation.formats: false` turns format checks off.
- **Lint.** [schema-format-type-mismatch](/techdocs/linter/rules/schema-format-type-mismatch)
  checks that a schema's `type` is one of its format's JSON types,
  [schema-format-deprecated](/techdocs/linter/rules/schema-format-deprecated) reports the
  deprecated formats with their replacement, and
  [schema-format-unknown](/techdocs/linter/rules/schema-format-unknown) (in the `strict`
  ruleset) reports formats that are neither in the registry nor declared.
- **Code and data generation.** The generators map formats to the language's types (the table
  says which), and `apigenie-generator data` and the server's generated responses make values
  that pass the checks.
- **Documentation.** The documentation components link a registry format to its registry page.

Formats of your own are declared in
[`openapi.custom_formats`](/techdocs/reference/cli-configuration#openapicustom_formats), with
the JSON type they apply to; they are accepted as they are. An entry naming a registry format
replaces that format's type and turns its check off.

## The registry

| Format | JSON types | Validated | Generated code | Notes |
| ------ | ---------- | --------- | -------------- | ----- |
| [`base64url`](https://spec.openapis.org/registry/format/base64url.html) | string | yes | string | **Deprecated** from OpenAPI 3.1: use `contentEncoding: base64url`. Binary data encoded as a url-safe string as defined in RFC4648 |
| [`binary`](https://spec.openapis.org/registry/format/binary.html) | string | no | bytes or a file | **Deprecated** from OpenAPI 3.1: use `contentMediaType`. any sequence of octets |
| [`byte`](https://spec.openapis.org/registry/format/byte.html) | string | yes | bytes | **Deprecated** from OpenAPI 3.1: use `contentEncoding: base64`. base64 encoded data as defined in RFC4648 |
| [`char`](https://spec.openapis.org/registry/format/char.html) | string | yes | string | A single character |
| [`commonmark`](https://spec.openapis.org/registry/format/commonmark.html) | string | no | string | commonmark-formatted text |
| [`date`](https://spec.openapis.org/registry/format/date.html) | string | yes | date | date as defined by full-date - RFC3339 |
| [`date-time`](https://spec.openapis.org/registry/format/date-time.html) | string | yes | date-time with offset | date and time as defined by date-time - RFC3339 |
| [`date-time-local`](https://spec.openapis.org/registry/format/date-time-local.html) | string | yes | local date-time (Java `LocalDateTime`, C# `DateTime`, Python `NaiveDatetime`) | RFC3339 date-time without the timezone component |
| [`decimal`](https://spec.openapis.org/registry/format/decimal.html) | string, number | yes | decimal (Java `BigDecimal`, C# `decimal`, Python `Decimal`) | A fixed point decimal number of unspecified precision and range |
| [`decimal128`](https://spec.openapis.org/registry/format/decimal128.html) | string, number | yes | decimal (Java `BigDecimal`, C# `decimal`, Python `Decimal`) | A decimal floating-point number with 34 significant decimal digits |
| [`double`](https://spec.openapis.org/registry/format/double.html) | number | yes | double-precision float | double precision floating point number |
| [`double-int`](https://spec.openapis.org/registry/format/double-int.html) | number | yes | 64-bit integer | an integer that can be stored in an IEEE 754 double-precision number without loss of precision |
| [`duration`](https://spec.openapis.org/registry/format/duration.html) | string | yes | duration (Python `timedelta`) | duration as defined by duration - RFC3339 |
| [`email`](https://spec.openapis.org/registry/format/email.html) | string | yes | string (FastAPI `EmailStr`) | An email address as defined as Mailbox in RFC5321 |
| [`float`](https://spec.openapis.org/registry/format/float.html) | number | yes | single-precision float | single precision floating point number |
| [`hostname`](https://spec.openapis.org/registry/format/hostname.html) | string | yes | string | A host name as defined by RFC1123 |
| [`html`](https://spec.openapis.org/registry/format/html.html) | string | no | string | HTML-formatted text |
| [`http-date`](https://spec.openapis.org/registry/format/http-date.html) | string | yes | string | date and time as defined by HTTP-date - RFC7231 |
| [`idn-email`](https://spec.openapis.org/registry/format/idn-email.html) | string | yes | string | An email address as defined as Mailbox in RFC6531 |
| [`idn-hostname`](https://spec.openapis.org/registry/format/idn-hostname.html) | string | yes | string | An internationalized host name as defined by RFC5890 |
| [`int16`](https://spec.openapis.org/registry/format/int16.html) | number | yes | integer (C# `short`, Go `int16`) | signed 16-bit integer |
| [`int32`](https://spec.openapis.org/registry/format/int32.html) | number | yes | integer | signed 32-bit integer |
| [`int64`](https://spec.openapis.org/registry/format/int64.html) | number, string | yes | 64-bit integer | signed 64-bit integer |
| [`int8`](https://spec.openapis.org/registry/format/int8.html) | number | yes | integer (C# `sbyte`, Go `int8`) | signed 8-bit integer |
| [`ipv4`](https://spec.openapis.org/registry/format/ipv4.html) | string | yes | string (FastAPI `IPv4Address`) | An IPv4 address as defined as dotted-quad by RFC2673 |
| [`ipv4-cidr`](https://spec.openapis.org/registry/format/ipv4-cidr.html) | string | yes | string | An IPv4 address in CIDR notation |
| [`ipv6`](https://spec.openapis.org/registry/format/ipv6.html) | string | yes | string (FastAPI `IPv6Address`) | An IPv6 address as defined by RFC4673 |
| [`ipv6-cidr`](https://spec.openapis.org/registry/format/ipv6-cidr.html) | string | yes | string | An IPv6 address in CIDR-style notation |
| [`iri`](https://spec.openapis.org/registry/format/iri.html) | string | yes | string | A Internationalized Resource Identifier as defined in RFC3987 |
| [`iri-reference`](https://spec.openapis.org/registry/format/iri-reference.html) | string | yes | string | A Internationalized Resource Identifier as defined in RFC3987 |
| [`json-pointer`](https://spec.openapis.org/registry/format/json-pointer.html) | string | yes | string | A JSON string representation of a JSON Pointer as defined in RFC6901 |
| [`language`](https://spec.openapis.org/registry/format/language.html) | string | yes | string | language tag as defined in RFC5646 |
| [`media-range`](https://spec.openapis.org/registry/format/media-range.html) | string | yes | string | A media type as defined by the media-range ABNF production in RFC9110. |
| [`password`](https://spec.openapis.org/registry/format/password.html) | string | no | string | a string that hints to obscure the value. |
| [`regex`](https://spec.openapis.org/registry/format/regex.html) | string | yes | string | A regular expression as defined in ECMA-262 |
| [`relative-json-pointer`](https://spec.openapis.org/registry/format/relative-json-pointer.html) | string | yes | string | A JSON string representation of a relative JSON Pointer as defined in draft RFC 01 |
| [`sf-binary`](https://spec.openapis.org/registry/format/sf-binary.html) | string | yes | string | structured fields byte sequence as defined in RFC8941 |
| [`sf-boolean`](https://spec.openapis.org/registry/format/sf-boolean.html) | string | yes | string | structured fields boolean as defined in RFC8941 |
| [`sf-decimal`](https://spec.openapis.org/registry/format/sf-decimal.html) | number | yes | string | structured fields decimal as defined in RFC8941 |
| [`sf-integer`](https://spec.openapis.org/registry/format/sf-integer.html) | number | yes | 64-bit integer | structured fields integer as defined in RFC8941 |
| [`sf-string`](https://spec.openapis.org/registry/format/sf-string.html) | string | yes | string | structured fields string as defined in RFC8941 |
| [`sf-token`](https://spec.openapis.org/registry/format/sf-token.html) | string | yes | string | structured fields token as defined in RFC8941 |
| [`time`](https://spec.openapis.org/registry/format/time.html) | string | yes | time | time as defined by full-time - RFC3339 |
| [`time-local`](https://spec.openapis.org/registry/format/time-local.html) | string | yes | local time (Java `LocalTime`, C# `TimeOnly`, Python `time`) | RFC3339 time without the timezone component |
| [`uint16`](https://spec.openapis.org/registry/format/uint16.html) | number | yes | integer (C# `ushort`, Go `uint16`) | unsigned 16-bit integer |
| [`uint32`](https://spec.openapis.org/registry/format/uint32.html) | number | yes | integer (Java `Long`, C# `uint`) | unsigned 32-bit integer |
| [`uint64`](https://spec.openapis.org/registry/format/uint64.html) | number, string | yes | integer (Java `BigInteger`, C# `ulong`) | unsigned 64-bit integer |
| [`uint8`](https://spec.openapis.org/registry/format/uint8.html) | number | yes | integer (C# `byte`, Go `uint8`) | unsigned 8-bit integer |
| [`unixtime`](https://spec.openapis.org/registry/format/unixtime.html) | number, string | yes | 64-bit integer (epoch seconds) | seconds since Jan 1st 1970 - IEEE1003.1-2024/POSIX.1-2024 |
| [`uri`](https://spec.openapis.org/registry/format/uri.html) | string | yes | URI (Java, C#) | A Uniform Resource Identifier as defined in RFC3986 |
| [`uri-reference`](https://spec.openapis.org/registry/format/uri-reference.html) | string | yes | string | A URI reference as defined in RFC3986 |
| [`uri-template`](https://spec.openapis.org/registry/format/uri-template.html) | string | yes | string | A URI Template as defined in RFC6570 |
| [`uuid`](https://spec.openapis.org/registry/format/uuid.html) | string | yes | UUID | A Universally Unique IDentifier as defined in RFC4122 |

"Generated code" names the type most generators use; the TypeScript and Zod generators keep
JSON's `number` and `string`, adding range checks for the integer formats. commonmark, html,
password and binary have no syntax to check.

The registry is vendored into API Genie and refreshed with `scripts/update-format-registry`; a
format added to the registry after an API Genie release is unknown to it until the next one, and
can be declared in `openapi.custom_formats` meanwhile.