JSON Structure: Alternate Names and Descriptions

1.2.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:¶

{
  "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"]
  }
}

1.2.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.¶

• 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"
      }
    }
  }
}

1.2.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].¶

• 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"]
  }
}