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-4291}[RFC 4291] |
|
|
|
{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] |
|
|
|
|
|
|
|
regular expressions as defined in {ECMA-262}[ECMA 262] |
|
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]. Hint: In the past we used |
|
|
|
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-alpha-2}[ISO 3166-1 alpha-2]. Hint: In the past we used |
|
|
|
three letter currency code — see {ISO-4217}[ISO 4217] |
|
|
|
Global Trade Item Number — see {GTIN}[GTIN] |
|
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
APIs {MUST} use the upper-case T as a separator between date and time and
upper-case Z at the end when generating dates as opposed to lower-case t,
z, space, or any other character. This is stricter than the
date/time format
as defined in RFC 3339, which leaves it up to the specification.
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.
When choosing between date and datetime formats you should take into account the following:
-
dateshould be used for properties where no exact point in time is required and day time-range is sufficient, for instance, document dates, birthdays, ETAs (estimated time of arrival). Without further context,dateimplies the time period from midnight to midnight in the local time zone. However, the timezone information can be also provided as an additional context information via other fields indicating location. -
datetimeshould be used in all other cases where an exact point in time is required, for instance, datetimes for supplier advice, specific processing events, fast delivery planning dates. As required in {MUST} use standard formats for date and time properties,datetimerequires the explicit time zone offset to be provided, which avoids misinterpretations and eliminates the need of an additional context to provide.
Properties and that are by design durations and time intervals should be
represented as strings formatted as defined by {ISO-8601}[ISO 8601]
({RFC-3339}#appendix-A[RFC 3339 Appendix A contains a grammar] for durations
and periods - the latter called time intervals in {ISO-8601}[ISO 8601]). ISO
8601:1-2019 defines an extension (..) to express open ended time intervals
that are very convenient in searches and are included in the below
{RFC-2234}[ABNF] grammar:
dur-second = 1*DIGIT "S"
dur-minute = 1*DIGIT "M" [dur-second]
dur-hour = 1*DIGIT "H" [dur-minute]
dur-time = "T" (dur-hour / dur-minute / dur-second)
dur-day = 1*DIGIT "D"
dur-week = 1*DIGIT "W"
dur-month = 1*DIGIT "M" [dur-day]
dur-year = 1*DIGIT "Y" [dur-month]
dur-date = (dur-day / dur-month / dur-year) [dur-time]
duration = "P" (dur-date / dur-time / dur-week)
period-explicit = iso-date-time "/" iso-date-time
period-start = iso-date-time "/" (duration / "..")
period-end = (duration / "..") "/" iso-date-time
period = period-explicit / period-start / period-endA time interval query parameters should use <time-property>_between instead
of the parameter tuple <time-property>_before/<time-property>_after, while
properties providing a time interval should be named <time-property>_interval.
As a specific case of {MUST} use standard data formats you must use the following standard formats:
-
Country codes: {ISO-3166-1-alpha-2}[ISO 3166-1-alpha-2] two letter country codes indicated via format
iso-3166-alpha-2in the OpenAPI specification. -
Language codes: {ISO-639-1}[ISO 639-1] two letter language codes indicated via format
iso-639-1in the OpenAPI specification. -
Language variant tags: {BCP47}[BCP 47] multi letter language tag indicated via format
bcp47in the OpenAPI specification. (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 format
iso-4217in the OpenAPI specification.
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.