03 Conventions

03.01 Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

03.02 Conventions Used in This Document

Any JSON object defined in this document MUST conform to RFC8259.

Some examples use the combination of a TypeScript single-line comment (//) followed by an ellipsis (...) as placeholder notation for content deemed irrelevant by the authors. These placeholders must of course be deleted or otherwise replaced, before attempting to validate the corresponding JSON code example.

Whitespace is used in the examples inside this document to help illustrate the data structures, but it is not required. Unquoted whitespace is not significant in JSON.

03.03 Type Definitions

In this document, a JSON object type defines the required and optional name-value pairs of a JSON object. An object belongs to a type — or "is of that type" — if it contains all required name-value pairs and only name-value pairs that are either required or optional for that type. Each name-value pair in a type definition specifies the name of the pair and the constraint on its value. Required name-value pairs are indicated by the keywords MUST or REQUIRED; optional name-value pairs by MAY, OPTIONAL, SHOULD, or RECOMMENDED, as defined in Section 03.01.

A type is a constraint on a JSON value. A JSON object type, as defined above, is a type that constrains an object by specifying its required and optional name-value pairs. A type may also constrain a non-object value by specifying the set of allowed values, for example, a number within a particular range, or a string equal to one of a specified set.

03.04 Representation of Data

In this document, TypeScript code is used to represent data, such as JSON object and JSON object type. However, the TypeScript code SHOULD NOT be considered the only form in which the data can be realized in an implementation.

03.99 Notes

The section 03.02 significantly references the standard RFC 7946.