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`