Display key patterns for schema.json-files

schema.json files have two basic types of documentation text: titles and descriptions. They can be declared at four levels:

  • The API itself
  • API resources
  • API resource properties
  • The API resource additionalProperties property

Title and description for the schema

The following display keys map to the title and description of a schema:

  • json.<localizationPrefix>.title
  • json.<localizationPrefix>.description

There are no examples of this in the base configuration.

Titles and descriptions for schema definitions

The following display keys map to the title and description of each schema definition:

  • json.<localizationPrefix>.definitions.<definitionName>.title
  • json.<localizationPrefix>.definitions.<definitionName>.description

For example, the description property for the Common API's Activity schema definition (declared in common_pl-1.0.schema.json) maps to json.common.v1.definitions.Activity.description.

Titles and descriptions for schema definition properties

The following display keys map to the title and description of each property on a given schema definition:

  • json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.title
  • json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.description

For example, the description property for the Common API's Activity schema definition's activityType property (declared in common_pl-1.0.schema.json) maps to json.common.v1.definitions.Activity.properties.activityType.description.

Titles and descriptions for a schema definition "additionalProperties" property

The following display keys map to the title and description of the additionalProperties property on a given schema definition:

  • json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.<propertyName>.title
  • json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.<propertyName>.description

For example, the description property for the Composite API's Headers schema definition's additionalProperties (declared in composite_pl-1.0.schema.json) maps to json.composite.v1.definitions.Headers.additionalProperties.description.

Summary of title and description mappings

Level Property Display key pattern Example
Schema title
json.<localizationPrefix>.title
json.common.v1.title
Schema description
json.<localizationPrefix>.description
json.common.v1.description
Schema definition title
json.<localizationPrefix>.definitions.<definitionName>.title
json.common.v1.definitions.Activity.title
Schema definition description
json.<localizationPrefix>.definitions.<definitionName>.description
json.common.v1.definitions.Activity.description
Schema definition property title
json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.title
json.common.v1.definitions.Activity.properties.activityType.title
Schema definition property description
json.<localizationPrefix>.definitions.<definitionName>.properties.<propertyName>.description
json.common.v1.definitions.Activity.properties.activityType.description
Schema definition additionalProperty title
json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.title
json.composite.v1.definitions.Headers.additionalProperties.title
Schema definition additionalProperty description
json.<localizationPrefix>.definitions.<definitionName>.additionalProperties.description
json.composite.v1.definitions.Headers.additionalProperties.description