Security, privacy, and related considerations

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

Accessibility considerations

Token metadata such as $description and $tagsSHOULD be written so that assistive tools can present tokens effectively. Consumers MUST preserve these text alternatives.

Internationalisation considerations

Token names and descriptions MAY use any Unicode characters. Consumers MUST preserve text as authored and SHOULD support right-to-left scripts.

Security considerations

Token documents MUST NOT execute arbitrary code. Consumers MUST reject $ref values that attempt directory traversal such as ../ and MUST NOT dereference remote references without explicit user opt‑in. Implementations SHOULD limit the size of retrieved resources. Test fixtures at tests/fixtures/negative/security/path-traversal and tests/fixtures/negative/security/remote-scheme illustrate these restrictions.

Privacy considerations

Token documents MAY include authorship and usage metadata. Producers SHOULD avoid embedding personally identifiable information, and consumers handling such data MUST comply with applicable privacy regulations.

Performance considerations

Producers SHOULD keep token documents small enough for static analysis and MAY split large systems into multiple files. Consumers SHOULD support streaming or incremental parsing and MAY cache resolved references to minimise network traffic.

See Platform guidance for the non-normative ecosystem advice that accompanied these requirements.