]> Microsoft Corporation

clemensv@microsoft.com

Web and Internet Transport Building Blocks for HTTP APIs Internet-Draft 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. About This Document The latest revision of this draft can be found at . Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

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.

Normative References In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This document describes the structure, content, construction, and semantics of language tags for use in cases where it is desirable to indicate the language used in an information object. It also describes how to register values for use in language tags and the creation of user-defined extensions for private interchange. This document, in combination with RFC 4647, replaces RFC 3066, which replaced RFC 1766. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. n.d.

Changes from draft-vasters-json-structure-alternate-names-00

• Fixed section heading levels throughout the document.

Acknowledgments TODO acknowledge.