data-formats.adoc

Data formats

{MUST} use JSON as payload data interchange format

Use JSON ({RFC-7159}[RFC 7159]) to represent structured (resource) data passed with HTTP requests and responses as body payload. The JSON payload must use a JSON object as top-level data structure (if possible) to allow for future extension. This also applies to collection resources, where you ad-hoc would use an array — see also [110].

Additionally, the JSON payload must comply to the more restrictive Internet JSON ({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} pass non-JSON media types using data specific standard formats

TBD

{SHOULD} use standard media types

You should use standard media types (defined in {media-types}[media type registry] of Internet Assigned Numbers Authority (IANA)) as content-type (or accept) header information. More specifically, for JSON payload you should use the standard media type application/json (or application/problem+json for [176]).

You should avoid using custom media types like application/x.sailpoint.article+json. Custom media types beginning with x bring no advantage compared to the standard media type for JSON, and make automated processing more difficult.

{MUST} 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].

{MUST} use standardized property formats

JSON Schema and OpenAPI define several data formats, e.g. date, time, email, and url, based on ISO and IETF standards. The following table lists these formats including additional formats useful in an e-commerce environment. You should use these formats, whenever applicable.

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.sailpoint.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.sailpoint.de/"
string	uri-template	{RFC-6570}[RFC 6570]	"/users/{id}"
string	uuid	{RFC-4122}[RFC 4122]	"e2ab873e-b295-11e9-9c02-…​"

Remark: Please note that this list of standard data formats is not exhaustive and everyone is encouraged to propose additions.

{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].

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

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

• Country codes: {ISO-3166-1-a2}[ISO 3166-1-alpha2] two letter country codes

  • Hint: It is "GB", not "UK", even though "UK" has seen some use at sailpoint

• Language codes: {ISO-639-1}[ISO 639-1] two letter language codes

• Language variant tags: {BCP47}[BCP 47]

  • It is a compatible extension of {ISO-639-1}[ISO 639-1], providing additional information for language usage, like region (using {ISO-3166-1-a2}[ISO 3166-1]), variant, script and others.

• Currency codes: {ISO-4217}[ISO 4217] three letter 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