Common Data Types

API types MUST use standard data formats.

Open API (based on JSON Schema Validation vocabulary) defines formats from ISO and IETF standards for date/time, integers/numbers and binary data.

APIs MUST use these formats, whenever applicable:

OpenAPI Formats Registry

The following list is provided for brevity and includes examples but please use OpenAPI Formats Registry as the master list.

OpenAPI format	OpenAPI type	Specification	Example
bigint	integer	arbitrarily large signed integer number	7.72E+19
binary	string	base64url encoded byte sequence following RFC7493 Section 4.4	"VGVzdA=="
byte	string	base64url encoded byte following RFC7493 Section 4.4	"VA=="
date	string	RFC3339 internet profile - subset of ISO 8601.	"2019-07-30"
date-time	string	RFC3339 internet profile - subset of ISO 8601.	"2019-07-30T06:43:40.252Z"
decimal	number	arbitrarily precise signed decimal number	3.141593
double	number	binary64 double precision decimal number - see IEEE 754-2008/ISO 60559:2011	3.141593
duration	string	RFC3339 - subset of ISO 8601.	"P1DT3H4S"
email	string	RFC5322	"example@example.com"
float	number	binary32 single precision decimal number - see IEEE 754-2008/ISO 60559:2011	3.141593
hostname	string	RFC1034	"www.example.com"
idn-email	string	RFC6531	"hello@bücher.example"
idn-hostname	string	RFC5890	"bücher.example"
int32	integer	4 byte signed integer between -231 and 231-1	7.72E+09
int64	integer	8 byte signed integer between -263 and 263-1	7.72E+14
ipv4	string	RFC2673	"104.75.173.179"
ipv6	string	RFC4291	"2600:1401:2::8a"
iri	string	RFC3987	"https://bücher.example/"
iri-reference	string	RFC3987	"/damenbekleidung-jacken-mäntel/"
json-pointer	string	RFC6901	"/items/0/id"
password	string		"secret"
period	string	RFC3339 - subset of ISO 8601.	"2022-06-30T14:52:44.276/PT48H" "PT24H/2023-07-30T18:22:16.315Z" "2024-05-15T09:48:56.317Z/.."
regex	string	regular expressions as defined in ECMA 262	"^[a-z0-9]+$"
relative-json-pointer	string	Relative JSON pointers	"1/id"
time	string	RFC3339 internet profile - subset of ISO 8601.	"06:43:40.252Z"
uri	string	RFC3986	"https://www.example.com/"
uri-reference	string	RFC3986	"/clothing/"
uri-template	string	RFC6570	"/users/{id}"
uuid	string	RFC4122	"e2ab873e-b295-11e9-9c02-…​"

Additional Formats

APIs SHOULD also consider using the following formats.

format	OpenAPI type	Specification	Example
bcp47	string	multi letter language tag - see BCP 47. It is a compatible extension of ISO 639-1 optionally with additional information for language usage, like region, variant, script.	"en-DE"
gtin-13	string	Global Trade Item Number - see GTIN	"5710798389878"
iso-3166-alpha-2	string	two letter country code - see ISO 3166-1 alpha-2.	"GB" Hint: It is "GB" not "UK".
iso-4217	string	three letter currency code - see ISO 4217	"EUR"
iso-639-1	string	two letter language code - see ISO 639-1.	"en"