JSON format

All RESTful services must support JSON (Javascript Object Notation RFC 7159).

Rule: Representation of structured data [rep-struct]

Structured data MUST be made available in JSON format (RFC 8259) with media type application/json. JSON text MUST be encoded using UTF-8.

Some legacy clients erroneously decode JSON message bodies using a non-UTF-8 encoding by default. To work around this, a charset parameter may be added to the Content-Type HTTP header, even though it has no meaning according to the JSON RFC.

Content-Type: application/json;charset=UTF-8

Media types of format application/<subtype>+json may be used for standardized JSON formats, though REST APIs should also accept requests using the generic application/json media type:

  • application/merge-patch+json for JSON Merge Patch message bodies (see Partial update)

  • application/problem+json for Problem Detail for HTTP APIs (RFC 9457) message bodies (see Error handling)

For extensibility, the JSON body of a RESTful request or response should always be a JSON object instead of an array, string, number, etc.

Rule: JSON object as top level structure [evo-object]

In a JSON request or response body, you MUST always return a JSON object (and not e.g. an array) as a top level data structure to support future extensibility.

JSON objects support compatible extension by adding new properties. This allows you to easily extend your response and e.g. add pagination later, without breaking backwards compatibility.

Rule: Naming of JSON properties [jsn-naming]

Following guidelines SHOULD be respected when determining a name for a JSON property:

  • use lowerCamelCase notation

    • also for abbreviations: all letters after the first should be lowercase

  • use American English

  • do not use underscores (_), hyphens (-) or dots (.) in a property name, nor use a digit as first letter

  • don’t use overly generic terms like info(rmation) and data as property name or as part of it

  • the name should refer to the business meaning of its value in relation to the object in which it is specified, rather than how it is defined

  • omit parts of the name that are already clear from the context

Properties used from other standards, like OpenID Connect and OAuth2, are allowed to deviate from this rule.

GOOD BAD

ssin

SSIN

streetRrn

street_RRN

customer

customerInformation

description

descriptionStringLength140

 
"country": {
  "nisCode": 150,
  "isoCode": "BE",
  "name": "Belgium"
}
 
"country": {
  "countryNisCode": 150,
  "countryIsoCode": "BE",
  "countryName": "Belgium"
}

In below example, enterpriseNumber should be used even though the enterprise prefix is clear by its context. This is because enterpriseNumber is a fixed denomination (declared in Crossroads Bank for Enterprises) and using just number would rather cause confusion to type of identifier being used.

{
  "name": "Proximus",
  "employerId": 93017373,
  "enterprise": {
    "enterpriseNumber": "0202239951",
    "href": "https://api.example.org/demo/v1/organizations/0202239951"
  }
}
Rule: Null values [jsn-null]

Properties without a value SHOULD be stripped from the JSON message, instead of having a null value.

For properties or parameters with a specified type, OpenAPI disallows null values by default, unless nullable: true is specified.

A notable exception to this rule are JSON Merge Patch requests, in which a null value indicates the removal of a JSON property.

Note that this rule doesn’t apply to empty values (e.g. empty strings "" or empty arrays []) as they are considered different from a null value.

NOK

OK

 
{
  "name": "Proximus",
  "employerId": 93017373,
  "enterprise": null
}
 
{
  "name": "Proximus",
  "employerId": 93017373
}

The JSON properties have no specific order inside a JSON object.

{
  "name": "Proximus",
  "employerId": 93017373
}
 
{
  "employerId": 93017373,
  "name": "Proximus"
}

Dates are written in ISO 8601 full-date format: yyyy-MM-dd

Dates don’t include time zone or offset information. See OpenAPI 3.0 data types and RFC 3339 section 5.6.

{
  "birthday": "1930-07-19"
}
Schema with date
type: object
properties:
  birthDay:
    type: string
    format: date

Date/time are written in ISO 8601 date-time format: yyyy-MM-dd’T’HH:mm:ss.SSSXXX

See JSON Schema Validation 7.3.1. date-time and RFC 3339 section 5.6. The fraction part .SSS for sub-second precision is optional and may be of any length. The time offset relative to UTC (XXX) is mandatory and may be Z (Zulu = offset 00:00) or of format ("+" / "-") time-hour ":" time-minute.

Example UTC
{
  "lastModification": "2016-04-24T09:26:01.5214Z"
}
Example with numeric offset
{
  "lastModification": "2016-04-24T11:26:00+02:00"
}
Schema with date-time
type: object
properties:
  lastModification:
    type: string
    format: date-time