JSON

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

For extensibility, the payload (if any) of a RESTful request or response should always be a JSON object instead of an array, string, number, etc (???). This way the request or response can always be extended with new properties ( ???).

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.

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

"country": {
  "nisCode": 150,
  "isoCode": "BE",
  "name": "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": "Belgacom",
  "employerId": 93017373,
  "enterprise": {
    "enterpriseNumber": "0202239951"
    "href": "/organizations/0202239951"
  }
}

Properties with a null value SHOULD be stripped from the JSON message.

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.

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

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

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

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

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

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

See OpenAPI 3.0 data types and RFC 3339 section 5.6.

{
  "birthday": "1930-07-19"
}

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 for sub second precision is optional and may be of any length.

{
  "lastModification": "2016-04-24T09:26:01.5214Z"
}

{
  "lastModification": "2016-04-24T11:26:00+02:00"
}