Mapper extension syntax

A mapper extension adheres to the following syntactic conventions:

• The extension is defined by a JSON object contained in the mappers field of the mapper extension file
• The name of the mapper extension matches that of the schema definition extension for the resource that is being extended
• The extension must have a schemaDefinition attribute that associates the mapper extension with the schema definition extension
• The extension must have a root attribute that associates the schema definition extension with a PolicyCenter entity
• The extension must have a properties attribute to contain the extended properties
• The name of each extended property must match that found in the associated schema definition extension
• Each extended property must have a path attribute pointing to a PolicyCenter entity field
• If the extended property value type is an object, then it must also have a mapper attribute that holds a relevant URI reference

The following listing shows a mapper extension for the Activity schema in the Common API. The extension maps an extended shortSubject_Ext resource property to the PolicyCenter Activity.ShortSubject entity field:

{
  . . .
  "mappers": {
    "Activity": {
      "schemaDefinition": "Activity",
      "root": "entity.Activity",
      "properties": {
        "shortSubject_Ext": {
          "path": "Activity.ShortSubject"
        }
      }
    }
  }
}

• Activity: The name of the mapper
• schemaDefinition: A mapping to the Activity schema definition
• root: A mapping of the Activity schema definition to the Activity entity in PolicyCenter
• shortSubject_Ext: A property name, as defined in the schema definition
• path: A path that associates the extended property with the Activity.ShortSubject entity field. Values can be chained. For example, the path for the display name of an account contact is AccountContact.Contact.DisplayName.

If a property value type is defined by a URI reference in the schema definition extension, then the extended property must also include a mapper attribute. The syntax for this value is #/mappers/ followed by the schema name. For example, if the property value type in the schema definition extension is "$ref": "#/definitions/SimpleReference", then the mapper attribute value would be "mapper": "#/mappers/SimpleReference".

The following listing shows an extended activityClass_Ext resource property that maps to the PolicyCenter Activity.ActivityClass entity field, which is backed by a typekey. The schema definition extension declares the property value type as "$ref": "#/definitions/TypeKeyReference". Therefore, it is necessary to include the mapper attribute:

{
  . . .
  "mappers": {
    "Activity": {
      "schemaDefinition": "Activity",
      "root": "entity.Activity",
      "properties": {
         "activityClass_Ext": {
           "path": "Activity.ActivityClass",
           "mapper": "#/mappers/TypeKeyReference"
        }
      }
    }
  }
}