XDM field type constraints

Last update: 2024-10-11
  • Topics:
  • Schemas
    View more on this topic
  • Created for:
  • Developer

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.

Getting started

Before using this guide, please review the basics of schema composition for an introduction to XDM schemas, classes, and schema field groups.

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 field groups 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 field groups and data types.

Base structure and examples

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. Custom fields names are case-insensitive and must have different names at the same level in your schema.

NOTE

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"
Number
{"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).

Mapping XDM types to other formats

The sections below describe how each XDM type maps to other common serialization formats:

NOTE

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.

Many standard XDM components use map types, and you can also define custom map fields if desired. The map type’s inclusion in the tables below is 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.

Parquet, Spark SQL, and Java

XDM type Parquet Spark SQL Java
String Type: BYTE_ARRAY
Annotation: UTF8
StringType java.lang.String
Number 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

Scala, .NET, and CosmosDB

XDM type Scala .NET CosmosDB
String String System.String String
Number 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

MongoDB, Aerospike, and Protobuf 2

XDM type MongoDB Aerospike Protobuf 2
String string String string
Number 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>

Defining XDM field types in the API

The Schema Registry API allows you to define custom fields through the use of formats and optional constraints. See the guide on defining custom fields in the Schema Registry API for more information.

On this page