data-formats.adoc

Data formats

{MUST} use JSON to encode structured data

Use JSON-encoded body payload for transferring structured data. The JSON payload must follow {RFC-7159}[RFC 7159] using a JSON object as top-level data structure (if possible) to allow for future extension. This also applies to collection resources, where one naturally would assume an array. See also [110].

Additionally, the JSON payload must comply to {RFC-7493}[RFC 7493]), particularly

• {RFC-7493}#section-2.1[Section 2.1] on encoding of characters, and

• {RFC-7493}#section-2.3[Section 2.3] on object constraints.

As a consequence, a JSON payload must

• use {RFC-7493}#section-2.1[UTF-8 encoding]

• consist of {RFC-7493}#section-2.1[valid Unicode strings], i.e. must not contain non-characters or surrogates, and

• contain only {RFC-7493}#section-2.3[unique member names] (no duplicate names).

{MAY} use non JSON media types for binary data or alternative content representations

Other media types may be used in following cases:

• Transferring binary data or data whose structure is not relevant. This is the case if payload structure is not interpreted and consumed by clients as is. Example of such use case is downloading images in formats JPG, PNG, GIF.

• In addition to JSON version alternative data representations (e.g. in formats PDF, DOC, XML) may be made available through content negotiation.

{SHOULD} encode embedded binary data in base64url

Exposing binary data using an alternative media type is generally preferred. See the rule above.

If an alternative content representation is not desired then binary data should be embedded into the JSON document as a base64url-encoded string property following {RFC-7493}#section-4.4[RFC 7493 Section 4.4].

{SHOULD} prefer standard media type name application/json

Previously, this guideline allowed the use of custom media types like application/x.zalando.article+json. This usage is not recommended anymore and should be avoided, except where it is necessary for cases of media type versioning. Instead, just use the standard media type name application/json (or application/problem+json for [176]).

Custom media types beginning with x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult. They are also {RFC-6838}#section-3.4[discouraged by RFC 6838].

{SHOULD} use standardized property formats

{https://json-schema.org/understanding-json-schema/reference/string.html#format}[JSON Schema] and {https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md#data-types}[Open API] define several universally useful property formats. The following table contains some additional formats that are particularly useful in an e-commerce environment.

Please notice that the list is not exhaustive and everyone is encouraged to propose additions.

type	format	Specification	Example
integer	int32		7721071004
integer	int64		772107100456824
integer	bigint		77210710045682438959
number	float	{IEEE-754-2008}[IEEE 754-2008]	3.1415927
number	double	{IEEE-754-2008}[IEEE 754-2008]	3.141592653589793
number	decimal		3.141592653589793238462643383279
string	bcp47	{BCP47}[BCP 47]	"en-DE"
string	byte	{RFC-7493}[RFC 7493]	"dGVzdA=="
string	date	{RFC-3339}[RFC 3339]	"2019-07-30"
string	date-time	{RFC-3339}[RFC 3339]	"2019-07-30T06:43:40.252Z"
string	email	{RFC-5322}[RFC 5322]	"[email protected]"
string	gtin-13	{GTIN}[GTIN]	"5710798389878"
string	hostname	{RFC-1034}[RFC 1034]	"www.zalando.de"
string	ipv4	{RFC-2673}[RFC 2673]	"104.75.173.179"
string	ipv6	{RFC-2673}[RFC 2673]	"2600:1401:2::8a"
string	iso-3166	{ISO-3166-1-a2}[ISO 3166-1 alpha-2]	"DE"
string	iso-4217	{ISO-4217}[ISO 4217]	"EUR"
string	iso-639	{ISO-639-1}[ISO 639-1]	"de"
string	json-pointer	{RFC-6901}[RFC 6901]	"/items/0/id"
string	password		"secret"
string	regex	{ECMA-262}[ECMA 262]	"^[a-z0-9]+$"
string	time	{RFC-3339}[RFC 3339]	"06:43:40.252Z"
string	uri	{RFC-3986}[RFC 3986]	"https://www.zalando.de/"
string	uri-template	{RFC-6570}[RFC 6570]	"/users/{id}"
string	uuid	{RFC-4122}[RFC 4122]	"e2ab873e-b295-11e9-9c02-…​"

{MUST} use standard date and time formats

JSON payload

Read more about date and time format in [126].

HTTP headers

Http headers including the proprietary headers use the {RFC-7231}#section-7.1.1.1[HTTP date format defined in RFC 7231].

{SHOULD} use standards for country, language and currency codes

Use the following standard formats for country, language and currency codes:

• {ISO-3166-1-a2}[ISO 3166-1-alpha2 country codes]

  • (It is "GB", not "UK", even though "UK" has seen some use at Zalando)

• {ISO-639-1}[ISO 639-1 language code]

  • {BCP47}[BCP 47] (based on {ISO-639-1}[ISO 639-1]) for language variants

• {ISO-4217}[ISO 4217 currency codes]

{MUST} define format for number and integer types

Whenever an API defines a property of type number or integer, the precision must be defined by the format as follows to prevent clients from guessing the precision incorrectly, and thereby changing the value unintentionally:

type	format	specified value range
integer	int32	integer between -231 and 231-1
integer	int64	integer between -263 and 263-1
integer	bigint	arbitrarily large signed integer number
number	float	{IEEE-754-2008}[IEEE 754-2008/ISO 60559:2011] binary32 decimal number
number	double	{IEEE-754-2008}[IEEE 754-2008/ISO 60559:2011] binary64 decimal number
number	decimal	arbitrarily precise signed decimal number

The precision must be translated by clients and servers into the most specific language types. E.g. for the following definitions the most specific language types in Java will translate to BigDecimal for Money.amount and int or Integer for the OrderList.page_size:

components:
  schemas:
    Money:
      type: object
      properties:
        amount:
          type: number
          description: Amount expressed as a decimal number of major currency units
          format: decimal
          example: 99.95
       ...

    OrderList:
      type: object
      properties:
        page_size:
          type: integer
          description: Number of orders in list
          format: int32
          example: 42