DTIF

Appearance

Format and serialisation ​

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

This chapter lists the reserved members available to every token document and outlines how references resolve across files.

$type ​

$type classifies the semantics of a token’s $value. The registry maintained by the specification editor defines the following well‑known categories:

  • Primitives: color, dimension, font, opacity, duration, easing, z-index
  • Composite: typography, shadow, gradient, filter, motion, elevation

Vendors MAY introduce custom types by registering them or by using $extensions. Consumers encountering an unknown $typeSHOULD warn but MUST NOT fail, and MUST preserve the token and all of its fields.

See Token types for detailed value semantics associated with each registered category.

$ref ​

$ref provides an alias to another token. Its value MUST be a JSON Pointer as defined in RFC 6901 or a URI containing a fragment that is a JSON Pointer.

Reference strings MUST include a # fragment containing the JSON Pointer. Local aliases therefore MUST start with #, while external references MUST append # and the pointer to a relative path or an HTTP(S) URI. Pointer segments MUST escape ~ and / characters as ~0 and ~1 respectively.

Tokens that declare $ref without $valueMUST also declare $type so that tooling can reason about the referenced semantics without resolving the pointer. Alias tokens MUST NOT include $value.

Consumers MUST resolve $ref using the following algorithm:

  1. If the string contains directory traversal segments such as ../ or %2e%2e, the token MUST be treated as invalid.
  2. Interpret the string as a URI-reference.
  3. If the reference has a network scheme, it MUST NOT be dereferenced without explicit user opt‑in; absent such opt‑in the token is invalid.
  4. If the reference has no scheme, resolve it against the location of the document containing the reference.
  5. If the resolved reference has a fragment, interpret it as a JSON Pointer and evaluate it against the referenced document.
  6. If the referenced token contains $ref, resolve it recursively.
  7. Maintain a set of visited references; if a reference recurs, the token MUST be treated as invalid. This detection MUST include references traversed while evaluating $overrides and their $fallback chains. When override resolution re-enters a previously visited target, consumers MUST report a circular dependency error.
  8. If evaluation fails to yield a value, the token is invalid.

Consumers MAY cache dereferenced documents. Resolution order is local tokens before external documents.

$description ​

Human-readable description. Tools MAY display it but MUST NOT require it.

$extensions ​

$extensions MUST be an object mapping extension identifiers to arbitrary JSON values. Keys MUST use lower-case reverse domain name notation with at least two labels, such as com.example, to avoid collisions. A registry of well-known namespaces is maintained by the specification editor. Consumers encountering a non-object $extensions member MUST treat it as absent.

Consumers MUST preserve unrecognised extensions.

Extension naming guidelines ​

Producers MUST scope proprietary data stored in $extensions using a stable prefix such as a reverse-DNS identifier (for example org.example.typography). To keep ecosystems interoperable, follow these practices:

  • Reuse namespaces listed in the DTIF registry before inventing new prefixes; submit additions when no suitable namespace exists.
  • Publish contact information and a canonical specification URL for each namespace so tools can resolve semantics and ask questions about versioning.
  • Provide namespace documentation alongside shared token payloads, especially when tokens leave the originating organisation.
  • Avoid overloading a namespace with unrelated features; define new subdomains when semantics diverge to prevent collisions.

Consumers MUST ignore unrecognised namespaces to maintain interoperability while surfacing warnings where helpful.