Open API (based on JSON Schema Validation vocabulary) defines formats from ISO and IETF standards for date/time, integers/numbers and binary data. You must use these formats, whenever applicable:
OpenAPI type |
OpenAPI format |
Specification | Example |
|---|---|---|---|
|
|
4 byte signed integer between -231 and 231-1 |
|
|
|
8 byte signed integer between -263 and 263-1 |
|
|
|
arbitrarily large signed integer number |
|
|
|
|
|
|
|
|
|
|
|
arbitrarily precise signed decimal number |
|
|
|
|
|
|
|
|
|
|
|
{RFC-3339}[RFC 3339] internet profile — subset of ISO 8601 |
|
|
|
{RFC-3339}[RFC 3339] internet profile — subset of ISO 8601 |
|
|
|
{RFC-3339}[RFC 3339] internet profile — subset of ISO 8601 |
|
|
|
{RFC-3339}[RFC 3339] internet profile — subset of ISO 8601 |
|
|
|
{RFC-3339}[RFC 3339] internet profile — subset of ISO 8601 |
|
|
|
|
|
|
|
{RFC-5322}[RFC 5322] |
|
|
|
{RFC-6531}[RFC 6531] |
|
|
|
{RFC-1034}[RFC 1034] |
|
|
|
{RFC-5890}[RFC 5890] |
|
|
|
{RFC-2673}[RFC 2673] |
|
|
|
{RFC-2673}[RFC 2673] |
|
|
|
{RFC-3986}[RFC 3986] |
|
|
|
{RFC-3986}[RFC 3986] |
|
|
|
{RFC-6570}[RFC 6570] |
|
|
|
{RFC-3987}[RFC 3987] |
|
|
|
{RFC-3987}[RFC 3987] |
|
|
{RFC-4122}[RFC 4122] |
|
|
|
|
{RFC-6901}[RFC 6901] |
|
|
|
|
Note: Formats bigint and decimal have been added to the OpenAPI defined formats — see also {MUST} define a format for number and integer types and {MUST} use standard formats for date and time properties below.
We add further OpenAPI formats that are useful especially in an e-commerce environment
e.g. language code, country code, and currency based other ISO and IETF standards.
You must use these formats, whenever applicable:
OpenAPI type |
format |
Specification | Example |
|---|---|---|---|
|
|
two letter language code — see {ISO-639-1}[ISO 639-1] |
|
|
|
multi letter language tag — see {BCP47}[BCP 47]. It is a compatible extension of {ISO-639-1}[ISO 639-1] optionally with additional information for language usage, like region, variant, script. |
|
|
|
two letter country code — see {ISO-3166-1-a2}[ISO 3166-1 alpha-2] |
|
|
|
three letter currency code — see {ISO-4217}[ISO 4217] |
|
|
|
Global Trade Item Number — see {GTIN}[GTIN] |
|
|
|
regular expressions as defined in {ECMA-262}[ECMA 262] |
|
Remark: Please note that this list of standard data formats is not exhaustive and everyone is encouraged to propose additions.
In {MUST} use standard data formats we added bigint and decimal to the OpenAPI defined formats.
As an implication, you must always provide one of the formats int32, int64, bigint
or float, double, decimal when you define an API property of
JSON type number or integer.
By this we prevent clients from guessing the precision incorrectly, and thereby
changing the value unintentionally. The precision must be translated by clients
and servers into the most specific language types; in Java, for instance, the number
type with decimal format will translate into BigDecimal and integer type with
int32 format will translate to int or Integer Java types.
You may expose binary data. You must use a standard media type and data format,
if applicable — see Rule 168. If no standard is available, you must define
the binary data as string typed property with binary format using base64url
encoding — as also described in {MUST} use standard data formats.
As a specific case of {MUST} use standard data formats, you must use the string typed formats
date, date-time, time, duration, or period for the definition of date and time properties.
The formats are based on the standard {RFC-3339}[RFC 3339] internet profile -- a
subset of ISO 8601
Exception: For passing date/time information via standard protocol headers, HTTP RFC 7231 requires to follow the date and time specification used by the Internet Message Format RFC 5322.
As defined by the standard, time zone offset may be used, however, we recommend
to only use times based on UTC without local offsets. For example 2015-05-28T14:07:17Z
rather than 2015-05-28T14:07:17+00:00. From experience we have learned that zone
offsets are not easy to understand and often not correctly handled. Note also that
zone offsets are different from local times which may include daylight saving time.
When it comes to storage, all dates should be consistently stored in UTC without
a zone offset. Localization should be done locally by the services that provide
user interfaces, if required.
Hint: We discourage using numerical timestamps. It typically creates issues with precision, e.g. whether to represent a timestamp as 1460062925, 1460062925000 or 1460062925.000. Date strings, though more verbose and requiring more effort to parse, avoid this ambiguity.
Schema based JSON properties that are by design durations and intervals could be strings formatted as defined by {ISO-8601}[ISO 8601] ({RFC-3339}#appendix-A[Appendix A of RFC 3339 contains a grammar] for durations).
As a specific case of {MUST} use standard data formats you must use the following standard formats:
-
Country codes: {ISO-3166-1-a2}[ISO 3166-1-alpha2] two letter country codes indicated via OpenAPI format
iso-3166 -
Language codes: {ISO-639-1}[ISO 639-1] two letter language codes indicated via OpenAPI format
iso-639 -
Language variant tags: {BCP47}[BCP 47] multi letter language tag indicated via OpenAPI format
bcp47. (It is a compatible extension of {ISO-639-1}[ISO 639-1] with additional optional information for language usage, like region, variant, script) -
Currency codes: {ISO-4217}[ISO 4217] three letter currency codes indicated via OpenAPI format
iso-4217
In some situations the API supports serving different representations of a specific resource (at the same URL)
e.g. JSON, PDF, TEXT, or HTML representations for an invoice resource.
You should use content negotiation
to support clients specifying via the standard HTTP headers
{Accept}, {Accept-Language}, {Accept-Encoding} which representation is best suited for their use case,
for example, which language of a document, representation / content format, or content encoding.
You [172] like application/json or application/pdf for defining the content
format in the {Accept} header.
Generating IDs can be a scaling problem in high frequency and near real time use cases. UUIDs solve this problem, as they can be generated without collisions in a distributed, non-coordinated way and without additional server round trips.
However, they also come with some disadvantages:
-
pure technical key without meaning; not ready for naming or name scope conventions that might be helpful for pragmatic reasons, e.g. we learned to use names for product attributes, instead of UUIDs
-
less usable, because…
-
cannot be memorized and easily communicated by humans
-
harder to use in debugging and logging analysis
-
less convenient for consumer facing usage
-
-
quite long: readable representation requires 36 characters and comes with higher memory and bandwidth consumption
-
not ordered along their creation history and no indication of used id volume
-
may be in conflict with additional backward compatibility support of legacy ids
UUIDs should be avoided when not needed for large scale id generation. Instead, for instance, server side support with id generation can be preferred ({POST} on id resource, followed by idempotent {PUT} on entity resource). Usage of UUIDs is especially discouraged as primary keys of master and configuration data, like brand-ids or attribute-ids which have low id volume but widespread steering functionality.
Please be aware that sequential, strictly monotonically increasing numeric identifiers may reveal critical, confidential business information, like order volume, to non-privileged clients.
In any case, we should always use string rather than number type for identifiers. This gives us more flexibility to evolve the identifier naming scheme. Accordingly, if used as identifiers, UUIDs should not be qualified using a format property.
Hint: Usually, random UUID is used - see UUID version 4 in {RFC-4122}[RFC 4122]. Though UUID version 1 also contains leading timestamps it is not reflected by its lexicographic sorting. This deficit is addressed by ULID (Universally Unique Lexicographically Sortable Identifier). You may favour ULID instead of UUID, for instance, for pagination use cases ordered along creation time.