Define XDM fields in the Schema Registry API

All Experience Data Model (XDM) fields are defined using the standard JSON Schema constraints that apply to their field type, with additional constraints for field names that are enforced by Adobe Experience Platform. The Schema Registry API allows you to define custom fields in your schemas through the use of formats and optional constraints. XDM field types are exposed by the field-level attribute, meta:xdmType.

NOTE

meta:xdmType is a system-generated value, and therefore you are not required to add this property to the JSON for your field when using the API (except when creating custom map types). Best practice is to use JSON Schema types (such as string and integer) with the appropriate min/max constraints as defined in the table below.

The following table outlines the appropriate formatting to define different field types, including those with optional properties. More information regarding optional properties and type-specific keywords is available through the JSON Schema documentation.

To begin, find the desired field type and use the sample code provided to build your API request for creating a field group or creating a data type.

XDM type Optional properties Example
String
  • pattern
  • minLength
  • maxLength
"sampleField": {
    "type": "string",
    "pattern": "^[A-Z]{2}$",
    "maxLength": 2
}
URI
"sampleField": {
  "type": "string",
  "format": "uri"
}
Enum
  • default
  • meta:enum
Constrained enum values are provided under the enum array, while optional customer-facing labels for each value can be provided under meta:enum:
"sampleField": {
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ],
  "meta:enum": {
      "value1": "Value 1",
      "value2": "Value 2",
      "value3": "Value 3"
  },
  "default": "value1"
}

Note that the meta:enum value does not declare an enumeration or drive any data validation on its own. In most cases, strings provided under meta:enum are also provided under enum to ensure that data is constrained. However, there are some use cases where meta:enum is provided without a corresponding enum array. See the tutorial on defining suggested values for more information.
Number
"sampleField": {
  "type": "number"
}
Long
"sampleField": {
  "type": "integer",
  "minimum": -9007199254740992,
  "maximum": 9007199254740992
}
Integer
"sampleField": {
  "type": "integer",
  "minimum": -2147483648,
  "maximum": 2147483648
}
Short
"sampleField": {
  "type": "integer",
  "minimum": -32768,
  "maximum": 32768
}
Byte
"sampleField": {
  "type": "integer",
  "minimum": -128,
  "maximum": 128
  }
Boolean
  • default
"sampleField": {
  "type": "boolean",
  "default": false
}
Date
"sampleField": {
  "type": "string",
  "format": "date",
  "examples": ["2004-10-23"]
}
DateTime
"sampleField": {
  "type": "string",
  "format": "date-time",
  "examples": ["2004-10-23T12:00:00-06:00"]
}
Array An array of basic scalar types (e.g. strings):
"sampleField": {
  "type": "array",
  "items": {
    "type": "string"
  }
}
An array of objects defined by another schema:
"sampleField": {
  "type": "array",
  "items": {
    "$ref": "https://ns.adobe.com/xdm/data/paymentitem"
  }
}
Object The type attribute of each sub-field defined under properties can be defined using any scalar type:
"sampleField": {
  "type": "object",
  "properties": {
    "field1": {
      "type": "string"
    },
    "field2": {
      "type": "number"
    }
  }
}
Object-type fields can defined by referencing the $id of a data type:
"sampleField": {
  "type": "object",
  "$ref": "https://ns.adobe.com/xdm/common/phoneinteraction"
}
Map A map-type field is essentially an object-type field with an unconstrained set of keys. Like objects, maps have a type value of object, but their meta:xdmType is explicitly set to map.

A map must not define any properties. It must define a single additionalProperties schema to describe the type of values contained within the map (each map can only contain a single data type). The type value must be either string or integer.

A map field with string-type values:
"sampleField": {
  "type": "object",
  "meta:xdmType": "map",
  "additionalProperties":{
    "type": "string"
  }
}
See the section below for more information on creating custom map types in XDM.

Creating custom map types

In order to support “map-like” data efficiently in XDM, objects may be annotated with a meta:xdmType set to map to make it clear that an object should be managed as if the key set were unconstrained. Data that is ingested into map fields must use string keys, and only string or integer values (as determined by additionalProperties.type).

XDM places the following restrictions on the use of this storage hint:

  • Map types MUST be of type object.
  • Map types MUST NOT have properties defined (in other words, they define “empty” objects).
  • Map types MUST include an additionalProperties.type field that describes the values that may be placed within the map, either string or integer.

Ensure that you are only using map-type fields when absolutely necessary, as they carry the following performance drawbacks:

  • Response time from Adobe Experience Platform Query Service degrades from three seconds to ten seconds for 100 million records.
  • Maps must have fewer than 16 keys or else risk further degradation.

The Platform user interface also has limitations in how it can extract the keys of map-type fields. Whereas object-type fields can be expanded, maps are displayed as a single field instead.

Next steps

This guide covered how to define different field types in the API. For more information how XDM field types are formatted, see the guide on XDM field type constraints.

On this page