In Experience Data Model (XDM) schemas, a field’s type constrains what kind of data the field can contain. This document provides an overview of each core field type, including the other serialization formats they can be mapped to and how to define your own field types in the API in order to enforce different constraints.
Before using this guide, please review the basics of schema composition for an introduction to XDM schemas, classes, and mixins.
If you plan on defining your own field types in the API, it is strongly recommended that you start with the Schema Registry developer guide to learn how to create mixins and data types to include your custom fields in. If you are using the Experience Platform UI to create your schemas, see the guide on defining fields in the UI to learn how implement constraints on fields that you define within custom mixins and data types.
XDM is built on top of JSON Schema, and therefore XDM fields inherit a similar syntax when defining their type. Understanding how different field types are represented in JSON Schema can help indicate the base constraints of each type.
See the API fundamentals guide for more information on JSON Schema and other underlying technologies in Platform APIs.
The following table outlines how each XDM type is represented in JSON Schema, along with an example value that conforms to the type:
XDM type | JSON Schema | Example |
---|---|---|
String |
{"type": "string"} |
"Platinum" |
Double |
{"type": "number"} |
12925.49 |
Long |
{ "type": "integer", "maximum": 9007199254740991, "minimum": -9007199254740991 } |
1478108935 |
Integer |
{ "type": "integer", "maximum": 2147483648, "minimum": -2147483648 } |
24906290 |
Short |
{ "type": "integer", "maximum": 32768, "minimum": -32768 } |
15781 |
Byte |
{ "type": "integer", "maximum": 128, "minimum": -128 } |
90 |
Date* |
{ "type": "string", "format": "date" } |
"2019-05-15" |
DateTime* |
{ "type": "string", "format": "date-time" } |
"2019-05-15T20:20:39+00:00" |
Boolean |
{"type": "string"} |
true |
*All date-formatted strings must conform to the ISO 8601 standard (RFC 3339, section 5.6).
The sections below describe how each XDM type maps to other common serialization formats:
Among the standard XDM types listed in the tables below, the Map type is also included. Maps are used in standard schemas when data is represented as keys that map to certain values, or where keys cannot reasonably be included in a static schema and must be treated as data values.
Map-type fields are reserved for industry and vendor schema usage and therefore cannot be used in custom resources that you define. The map type’s inclusion in the tables below is only intended to help you determine how to map your existing data to XDM if it is currently stored in any of the formats listed below.
XDM type | Parquet | Spark SQL | Java |
---|---|---|---|
String | Type: BYTE_ARRAY Annotation: UTF8 |
StringType |
java.lang.String |
Double | Type: DOUBLE |
LongType |
java.lang.Double |
Long | Type: INT64 |
LongType |
java.lang.Long |
Integer | Type: INT32 Annotation: INT_32 |
IntegerType |
java.lang.Integer |
Short | Type: INT32 Annotation: INT_16 |
ShortType |
java.lang.Short |
Byte | Type: INT32 Annotation: INT_8 |
ByteType |
java.lang.Short |
Date | Type: INT32 Annotation: DATE |
DateType |
java.util.Date |
DateTime | Type: INT64 Annotation: TIMESTAMP_MILLIS |
TimestampType |
java.util.Date |
Boolean | Type: BOOLEAN |
BooleanType |
java.lang.Boolean |
Map | MAP -annotated group( <key-type> must be STRING ) |
MapType ( keyType must be StringType ) |
java.util.Map |
XDM type | Scala | .NET | CosmosDB |
---|---|---|---|
String | String |
System.String |
String |
Double | Double |
System.Double |
Number |
Long | Long |
System.Int64 |
Number |
Integer | Int |
System.Int32 |
Number |
Short | Short |
System.Int16 |
Number |
Byte | Byte |
System.SByte |
Number |
Date | java.util.Date |
System.DateTime |
String |
DateTime | java.util.Date |
System.DateTime |
String |
Boolean | Boolean |
System.Boolean |
Boolean |
Map | Map |
(N/A) | object |
XDM type | MongoDB | Aerospike | Protobuf 2 |
---|---|---|---|
String | string |
String |
string |
Double | double |
Double |
double |
Long | long |
Integer |
int64 |
Integer | int |
Integer |
int32 |
Short | int |
Integer |
int32 |
Byte | int |
Integer |
int32 |
Date | date |
Integer (Unix milliseconds) |
int64 (Unix milliseconds) |
DateTime | timestamp |
Integer (Unix milliseconds) |
int64 (Unix milliseconds) |
Boolean | bool |
Integer (0/1 binary) |
bool |
Map | object |
map |
map<key_type, value_type> |
All 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 Experience Platform. The Schema Registry API allows you to define additional field types through the use of formats and optional constraints. XDM field types are exposed by the field-level attribute, meta:xdmType
.
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. 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 mixin or creating a data type.
XDM type | Optional properties | Example |
---|---|---|
String |
|
"sampleField": { "type": "string", "pattern": "^[A-Z]{2}$", "maxLength": 2 } |
URI |
"sampleField": { "type": "string", "format": "uri" } |
|
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" } |
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 |
|
"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 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). Values may be any valid XDM type attribute, or a reference to another schema using a $ref attribute.A map field with string-type values: "sampleField": { "type": "object", "additionalProperties":{ "type": "string" } }A map field with arrays of strings for values: "sampleField": { "type": "object", "additionalProperties":{ "type": "array", "items": { "type": "string" } } }A map field that references another data type: "sampleField": { "type": "object", "additionalProperties":{ "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } } |