JSON Structure: Alternate Names and Descriptions
draft-vasters-json-structure-alternate-names-01

Building Blocks for HTTP APIs C. Vasters
Internet-Draft Microsoft Corporation
Intended status: Standards Track 4 December 2025
Expires: 7 June 2026
 JSON Structure: Alternate Names and Descriptions
 draft-vasters-json-structure-alternate-names-01
Abstract
 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
 This note is to be removed before publishing as an RFC.
 The latest revision of this draft can be found at https://json-
 structure.github.io/alternate-names/draft-vasters-json-structure-
 alternate-names.html. Status information for this document may be
 found at https://datatracker.ietf.org/doc/draft-vasters-json-
 structure-alternate-names/.
 Source for this draft and an issue tracker can be found at
 https://github.com/json-structure/alternate-names.
Status of This Memo
 This Internet-Draft is submitted in full conformance with the
 provisions of BCP 78 and BCP 79.
 Internet-Drafts are working documents of the Internet Engineering
 Task Force (IETF). Note that other groups may also distribute
 working documents as Internet-Drafts. The list of current Internet-
 Drafts is at https://datatracker.ietf.org/drafts/current/.
 Internet-Drafts are draft documents valid for a maximum of six months
 and may be updated, replaced, or obsoleted by other documents at any
 time. It is inappropriate to use Internet-Drafts as reference
 material or to cite them other than as "work in progress."
 This Internet-Draft will expire on 7 June 2026.
Vasters Expires 7 June 2026 [Page 1]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
Copyright Notice
 Copyright (c) 2025 IETF Trust and the persons identified as the
 document authors. All rights reserved.
 This document is subject to BCP 78 and the IETF Trust's Legal
 Provisions Relating to IETF Documents (https://trustee.ietf.org/
 license-info) in effect on the date of publication of this document.
 Please review these documents carefully, as they describe your rights
 and restrictions with respect to this document. Code Components
 extracted from this document must include Revised BSD License text as
 described in Section 4.e of the Trust Legal Provisions and are
 provided without warranty as described in the Revised BSD License.
Table of Contents
 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
 2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . 3
 3. Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . 3
 3.1. The altnames Keyword . . . . . . . . . . . . . . . . . . 3
 3.2. The altenums Keyword . . . . . . . . . . . . . . . . . . 4
 3.3. The descriptions Keyword . . . . . . . . . . . . . . . . 5
 4. Enabling the Annotations . . . . . . . . . . . . . . . . . . 7
 5. Security and Interoperability Considerations . . . . . . . . 7
 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8
 7. Normative References . . . . . . . . . . . . . . . . . . . . 8
 Changes from draft-vasters-json-structure-alternate-names-00 . . 8
 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . 8
 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 8
1. Introduction
 This document is an extension to JSON Structure Core [JSTRUCT-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.
Vasters Expires 7 June 2026 [Page 2]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all
 capitals, as shown here.
3. Keywords
 This section defines the alternate names and symbols annotations.
3.1. 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 [RFC4646].
 * 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:
Vasters Expires 7 June 2026 [Page 3]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
 {
 "Person": {
 "type": "object",
 "altnames": {
 "json": "person_data",
 "lang:en": "Person",
 "lang:de": "Person"
 },
 "properties": {
 "firstName": {
 "type": "string",
 "altnames": {
 "json": "first_name",
 "lang:en": "First Name",
 "lang:de": "Vorname"
 }
 },
 "lastName": {
 "type": "string",
 "altnames": {
 "json": "last_name",
 "lang:en": "Last Name",
 "lang:de": "Nachname"
 }
 }
 },
 "required": ["firstName", "lastName"]
 }
 }
3.2. 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.
Vasters Expires 7 June 2026 [Page 4]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
 * 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.
 {
 "Color": {
 "type": "string",
 "enum": ["RED", "GREEN", "BLUE"],
 "altenums": {
 "json": {
 "RED": "#FF0000",
 "GREEN": "#00FF00",
 "BLUE": "#0000FF"
 },
 "lang:en": {
 "RED": "Red",
 "GREEN": "Green",
 "BLUE": "Blue"
 },
 "lang:de": {
 "RED": "Rot",
 "GREEN": "Grün",
 "BLUE": "Blau"
 }
 }
 }
 }
3.3. 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
 [RFC4646].
Vasters Expires 7 June 2026 [Page 5]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
 * 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:
 {
 "Person": {
 "type": "object",
 "descriptions": {
 "lang:en": "A person object with first and last name",
 "lang:de": "Ein Person-Objekt mit Vor- und Nachnamen",
 "lang:fr": "Un objet personne avec prénom et nom de famille",
 "lang:cn": "一个带有名字和姓氏的人对象",
 "lang:jp": "名前と姓を持つ人物オブジェクト"
 },
 "properties": {
 "firstName": {
 "type": "string",
 "descriptions": {
 "lang:en": "The first name of the person",
 "lang:de": "Der Vorname der Person",
 "lang:fr": "Le prénom de la personne",
 "lang:cn": "人的名字",
 "lang:jp": "人の名前"
 }
 },
 "lastName": {
 "type": "string",
 "descriptions": {
 "lang:en": "The last name of the person",
 "lang:de": "Der Nachname der Person",
 "lang:fr": "Le nom de famille de la personne",
 "lang:cn": "人的姓氏",
 "lang:jp": "人の姓"
 }
 }
 },
 "required": ["firstName", "lastName"]
 }
 }
Vasters Expires 7 June 2026 [Page 6]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
4. 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:
 {
 "$schema": "https://json-structure.org/meta/extended/v0/#",
 "$id": "myschema",
 "$uses": [
 "JSONStructureAlternateNames"
 ],
 "type": "object",
 "properties": {
 "name": {
 "type": "string",
 "altnames": {
 "lang:fr": "Nom"
 }
 }
 }
 }
 The annotation are enabled by default in the validation meta-schema:
 {
 "$schema": "https://json-structure.org/meta/validation/v0/#",
 "$id": "myschema",
 "type": "object",
 "properties": {
 "name": {
 "type": "string",
 "altnames": {
 "lang:fr": "Nom"
 }
 }
 }
 }
5. 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.
Vasters Expires 7 June 2026 [Page 7]
Internet-Draft JSON Structure: Alternate Names and Desc December 2025
6. IANA Considerations
 This document has no IANA actions.
7. Normative References
 [JSTRUCT-CORE]
 Vasters, C., "JSON Structure Core", n.d., <https://json-
 structure.github.io/core/draft-vasters-json-structure-
 core.html>.
 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
 Requirement Levels", BCP 14, RFC 2119,
 DOI 10.17487/RFC2119, March 1997,
 <https://www.rfc-editor.org/rfc/rfc2119>.
 [RFC4646] Phillips, A. and M. Davis, "Tags for Identifying
 Languages", RFC 4646, DOI 10.17487/RFC4646, September
 2006, <https://www.rfc-editor.org/rfc/rfc4646>.
 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
 May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.
Changes from draft-vasters-json-structure-alternate-names-00
 * Fixed section heading levels throughout the document.
Acknowledgments
 TODO acknowledge.
Author's Address
 Clemens Vasters
 Microsoft Corporation
 Email: clemensv@microsoft.com
Vasters Expires 7 June 2026 [Page 8]