Getting startedFormats

Formats

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