Architecture and model

Sections marked as "Note" or "Example" are non-normative. Everything else is normative.

This chapter defines the structural foundations for token documents and builds on the terminology definitions.

Document structure

A token document MUST be a JSON object. Members whose names do not begin with $ MUST be treated as tokens or collections. Members beginning with $ are reserved for this specification.

Property names are case-sensitive and MAY contain any Unicode characters.

Documents MAY contain a top-level $extensions member for metadata that applies to the entire document.

Tokens and collections

A token is an object with a $value member. A collection is an object without a $value member whose properties are tokens or collections.

Collections and tokens MAY be nested arbitrarily.

Consumers MUST NOT execute code when processing token documents.

UTF-8 encoding

Token documents MUST be encoded in UTF‑8. $description values MAY contain text in any natural language and MUST follow the Unicode Standard.

Versioning

Token documents SHOULD provide a $version member that MUST conform to Semantic Versioning 2.0.0. Consumers encountering a future major version SHOULD warn and MAY treat the document as incompatible. Consumers encountering a future minor or patch version MAY continue processing.

See Format and serialisation and Token types for the normative definition of reserved members and Change management for guidance on versioning strategies.