MUST use published standard codes [14]

We only speak of “codes” when these are published and versioned. In other cases the values should be referred to as “abbreviations”. We distinguish between short and long values, where short values can either be codes or abbreviations and a long value is a human readable title.

Implementation style enums in order of preference:

1. Use published (ISO) standard codes like country code and units of measure
2. Use market (CIM/EDSN) standard codes like supply direction and segment
3. Use natural language in UPPER_SNAKE_CASE for a maximum of 3 words
4. API specific abbreviations

Style 1

• Make a reference to the published code list in the description of the field

Style 2

• System codes like SAP “E0001” is not a allowed value for this style
• Put the short and long names in the description of the field in the following format

supplyDirection:
  description: LVR = Levering (consumptie), TLV = Teruglevering (productie), CMB = Combinatie

Style 3

• HTTP-requests: SHOULD use enum values in UPPER_SNAKE_CASE [27]

Style 4

• Keep the abbreviations short (max 6 characters) and in uppercase.

Other considerations

• HTTP-requests: SHOULD use open-ended list of values for enumerations [28]

If desired the provider can offer a long title in addition to the short abbreviation or code. Both field should be on the same level and not in a nested object. This is to facilitate adding additional long values later without breaking the compatibility.

Typically the short values is used for updates while both are returned on retrieval of the resource. This the consumer already implemented a short value, the long value can be added later with a field suffix “Long”. If the long value is already implemented a short value can be added later with the field suffix “Short”.

{
  "connectionClass": "CAI",
  "connectionClassLong": "Kast Kabeltelevisie"
}

SHOULD use enumeration for static values [15]

For static values an enumeration is preferred. Both consumer and provider should validate the allowed code values. See also: “MUST use published standard codes” See also: “SHOULD use open-ended list of values for enumerations”

MUST use ISO 8601 date and time format [16]

Must use the ISO 8601 date time format in Zulu (UTC) like: 2020-04-23T15:20:36Z. Use a full ISO date-time when possible.