JSON Structure: Alternate Names and Descriptions

Introduction This document is an extension to JSON Structure Core . It defines three annotation keywords, altnames, altenums, and descriptions, which allow schema authors to provide alternative identifiers, display names, and multi-variant descriptions for types, properties, and enumeration values. These annotations facilitate mapping between internal schema identifiers and external data representations (e.g., JSON keys that do not conform to identifier rules) and support internationalization by enabling localized labels.

Conventions 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 when, and only when, they appear in all capitals, as shown here.

Keywords This section defines the alternate names and symbols annotations.

The altnames Keyword The altnames keyword provides alternative names for a named type or property. Alternate names are not subject to the identifier syntax restrictions imposed on name and MAY be used to map internal schema names to external representations. The value of altnames MUST be a map where each key is a purpose indicator and each value is a string representing an alternate name.

The key "json" is RESERVED. When used, it specifies the property key to use for a property when encoded in JSON. This allows for JSON keys that do not conform to identifier rules.
Keys starting with the prefix "lang:" (e.g., "lang:en", "lang:fr") are RESERVED for localized display names. The suffix after the colon specifies the language code. The language code MUST conform to .
Other keys are allowed for custom usage, provided they do not conflict with the reserved keys or prefixes.

The altnames keyword MAY be included in any schema element that has an explicit name (i.e., named types or properties). When present, the alternate names provide additional mappings that schema processors MAY use for encoding, decoding, or user interface display. Example:

The altenums Keyword The altenums keyword provides alternative representations (symbols) for enumeration values defined by a type using the enum keyword. Alternate symbols allow schema authors to map internal enum values to external codes or localized display symbols. The value of altenums MUST be a JSON object (map) where each key is a purpose indicator and each corresponding value is an object mapping each enumeration value (as defined in the enum array) to its alternate symbol.

The key "json" is RESERVED and MUST be used to specify alternate symbols for JSON encoding.
Keys beginning with "lang:" (e.g., "lang:en", "lang:es") are RESERVED for providing localized alternate symbols.
Additional keys are permitted for custom usage, subject to no conflicts with reserved keys or prefixes.

The altenums keyword MUST be used only with schemas that include an enum keyword. When present, it provides alternative representations for each enumeration value that schema processors MAY use for encoding or display purposes.

The descriptions Keyword The descriptions keyword provides multi-variant descriptions as an alternative to the description keyword. It allows schema authors to provide localized or context-specific descriptions for types, properties, or enumeration values. The value of descriptions MUST be a map where each key is a purpose indicator and each value is a string representing a description.

Keys beginning with "lang:" (e.g., "lang:en", "lang:fr") are RESERVED for localized descriptions. The suffix after the colon specifies the language code. The language code MUST conform to .
Other keys are allowed for custom usage, provided they do not conflict with the reserved keys or prefixes.

The descriptions keyword MAY be included in any schema element that can have a description. When present, the descriptions provide additional mappings that schema processors MAY use for user interface display. Example:

Enabling the Annotations Alternate names and symbols annotations can be enabled in a schema or meta-schema by adding the JSONSchemaAlternateNames key to the $uses clause when referencing the extended meta-schema: The annotation are enabled by default in the validation meta-schema:

Security and Interoperability Considerations Alternate names and symbols annotations do not affect the validation of instance data. They are purely metadata and MUST be ignored by validators that do not support this extension. However, applications that rely on alternate names for mapping or localization MUST implement appropriate safeguards to ensure that the alternate identifiers are used consistently.

IANA Considerations This document has no IANA actions.