Show Menu
TOPICS×

Appendix

This document provides supplemental information related to working with the Schema Registry API.

Compatibility Mode

Experience Data Model (XDM) is a publicly documented specification, driven by Adobe to improve the interoperability, expressiveness, and power of digital experiences. Adobe maintains the source code and formal XDM definitions in an open source project on GitHub . These definitions are written in XDM Standard Notation, using JSON-LD (JavaScript Object Notation for Linked Data) and JSON Schema as the grammar for defining XDM schemas.
When looking at formal XDM definitions in the public repository, you can see that standard XDM differs from what you see in Adobe Experience Platform. What you are seeing in Experience Platform is called Compatibility Mode, and it provides a simple mapping between standard XDM and the way it is used within Platform.

How Compatibility Mode works

Compatibility Mode allows the XDM JSON-LD model to work with existing data infrastructure by altering values within standard XDM while keeping the semantics the same. It uses a nested JSON structure, displaying schemas in a tree-like format.
The main difference you will notice between standard XDM and Compatibility Mode is the removal of the "xdm:" prefix for field names.
The following is a side-by-side comparison showing birthday-related fields (with "description" attributes removed) in both standard XDM and Compatibility Mode. Notice that the Compatibility Mode fields include a reference to the XDM field and its data type in the "meta:xdmField" and "meta:xdmType" attributes.
Standard XDM Compatibility Mode
        {
          "xdm:birthDate": {
              "title": "Birth Date",
              "type": "string",
              "format": "date",
          },
          "xdm:birthDayAndMonth": {
              "title": "Birth Date",
              "type": "string",
              "pattern": "[0-1][0-9]-[0-9][0-9]",
          },
          "xdm:birthYear": {
              "title": "Birth year",
              "type": "integer",
              "minimum": 1,
              "maximum": 32767
        }
      

        {
          "birthDate": {
              "title": "Birth Date",
              "type": "string",
              "format": "date",
              "meta:xdmField": "xdm:birthDate",
              "meta:xdmType": "date"
          },
          "birthDayAndMonth": {
              "title": "Birth Date",
              "type": "string",
              "pattern": "[0-1][0-9]-[0-9][0-9]",
              "meta:xdmField": "xdm:birthDayAndMonth",
              "meta:xdmType": "string"
          },
          "birthYear": {
              "title": "Birth year",
              "type": "integer",
              "minimum": 1,
              "maximum": 32767,
              "meta:xdmField": "xdm:birthYear",
              "meta:xdmType": "short"
        }
      

Why is Compatibility Mode necessary?

Adobe Experience Platform is designed to work with multiple solutions and services, each with their own technical challenges and limitations (for example, how certain technologies handle special characters). In order to overcome these limitations, Compatibility Mode was developed.
Most Experience Platform services including Catalog, Data Lake, and Real-time Customer Profile use Compatibility Mode in lieu of standard XDM. The Schema Registry API also uses Compatibility Mode, and the examples in this document are all shown using Compatibility Mode.
It is worthwhile to know that a mapping takes place between standard XDM and the way it is operationalized in Experience Platform, but it should not affect your use of Platform services.
The open source project is available to you, but when it comes to interacting with resources through the Schema Registry, the API examples in this document provide the best practices you should know and follow.

Defining XDM field types in the API

XDM schemas are defined using JSON Schema standards and basic field types, with additional constraints for field names which are enforced by Experience Platform. XDM allows you to define additional field types through the use of formats and optional constraints. The 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. 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 scalar field types and more specific field types using 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.
Desired Type (meta:xdmType) JSON (JSON Schema) Code Sample
string type: string Optional properties:
  • pattern
  • minLength
  • maxLength
        "sampleField": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "maxLength": 2
        }
      

uri (xdmType:string) type: string format: uri
        "sampleField": {
          "type": "string",
          "format": "uri"
        }
      

enum (xdmType: string) type: string Optional property:
  • default
Specify customer-facing option labels using "meta:enum":
        "sampleField": {
          "type": "string",
          "enum": [
              "value1",
              "value2",
              "value3"
          ],
          "meta:enum": {
              "value1": "Value 1",
              "value2": "Value 2",
              "value3": "Value 3"
          },
          "default": "value1"
        }
      

number type: number minimum: ±2.23×10^308 maximum: ±1.80×10^308
        "sampleField": {
          "type": "number"
        }
      

long type: integer maximum:2^53+1 minimum:-2^53+1
        "sampleField": {
          "type": "integer",
          "minimum": -9007199254740992,
          "maximum": 9007199254740992
        }
      

int type: integer maximum:2^31 minimum:-2^31
        "sampleField": {
          "type": "integer",
          "minimum": -2147483648,
          "maximum": 2147483648
        }
      

short type: integer maximum:2^15 minimum:-2^15
        "sampleField": {
          "type": "integer",
          "minimum": -32768,
          "maximum": 32768
        }
      

byte type: integer maximum:2^7 minimum:-2^7
        "sampleField": {
          "type": "integer",
          "minimum": -128,
          "maximum": 128
          }
      

boolean type: boolean {true, false} Optional property:
  • default
        "sampleField": {
          "type": "boolean",
          "default": false
        }
      

date type: string format: date
        "sampleField": {
          "type": "string",
          "format": "date",
          "examples": ["2004-10-23"]
        }
      

Date as defined by RFC 3339, section 5.6 , where "full-date" = date-fullyear "-" date-month "-" date-mday (YYYY-MM-DD)
date-time type: string format: date-time
        "sampleField": {
          "type": "string",
          "format": "date-time",
          "examples": ["2004-10-23T12:00:00-06:00"]
        }
      

Date-Time as defined by RFC 3339, section 5.6 , where "date-time" = full-date "T" full-time: (YYYY-MM-DD'T'HH:MM:SS.SSSSX)
array type: array items.type can be defined using any scalar type:
        "sampleField": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      

Array of objects defined by another schema:
        "sampleField": {
          "type": "array",
          "items": {
            "$ref": "id"
          }
        }
      

Where "id" is the {id} of the reference schema.
object type: object properties.{field}.type can be defined using any scalar type:
        "sampleField": {
          "type": "object",
          "properties": {
            "field1": {
              "type": "string"
            },
            "field2": {
              "type": "number"
            }
          }
        }
      

Field of type "object" that is defined by a reference schema:
        "sampleField": {
          "type": "object",
          "$ref": "id"
        }
      

Where "id" is the {id} of the reference schema.
map type: object Note: Use of the 'map' data type is reserved for industry and vendor schema usage and is not available for use in tenant defined fields. It is used in standard schemas when data is represented as keys that map to some value, or where keys cannot reasonably be included in a static schema and must be treated as data values. A 'map' MUST NOT define any properties. It MUST define a single "[!UICONTROL additionalProperties]" schema to describe the type of values contained in the 'map'. A 'map' in XDM can contain only a single data type. Values may be any valid XDM schema definition, including an array or an object, or as a reference to another schema (via $ref). Map field with values of type 'string':
        "sampleField": {
          "type": "object",
          "additionalProperties":{
            "type": "string"
          }
        }
      

Map field with values being an array of strings:
        "sampleField": {
          "type": "object",
          "additionalProperties":{
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      

Map field that references another schema:
        "sampleField": {
          "type": "object",
          "additionalProperties":{
            "$ref": "id"
          }
        }
      

Where "id" is the {id} of the reference schema.

Mapping XDM types to other formats

The table below describes the mapping between "meta:xdmType" and other serialization formats.
XDM Type
(meta:xdmType)
JSON
(JSON Schema)
Parquet
(type/annotation)
Spark SQL
Java
Scala
.NET
CosmosDB
MongoDB
Aerospike
Protobuf 2
string
type:string
BYTE_ARRAY/UTF8
StringType
java.lang.String
String
System.String
String
string
String
string
number
type:number
DOUBLE
DoubleType
java.lang.Double
Double
System.Double
Number
double
Double
double
long
type:integer
maximum:253+1
INT64
LongType
java.lang.Long
Long
System.Int64
Number
long
Integer
int64
int
type:integer
maximum:231
INT32/INT_32
IntegerType
java.lang.Integer
Int
System.Int32
Number
int
Integer
int32
short
type:integer
maximum:215
INT32/INT_16
ShortType
java.lang.Short
Short
System.Int16
Number
int
Integer
int32
byte
type:integer
maximum:27
INT32/INT_8
ByteType
java.lang.Short
Byte
System.SByte
Number
int
Integer
int32
boolean
type:boolean
BOOLEAN
BooleanType
java.lang.Boolean
Boolean
System.Boolean
Boolean
bool
Integer
Integer
date
type:string
format:date
(RFC 3339, section 5.6)
INT32/DATE
DateType
java.util.Date
java.util.Date
System.DateTime
String
date
Integer
(unix millis)
int64
(unix millis)
date-time
type:string
format:date-time
(RFC 3339, section 5.6)
INT64/TIMESTAMP_MILLIS
TimestampType
java.util.Date
java.util.Date
System.DateTime
String
timestamp
Integer
(unix millis)
int64
(unix millis)
map
object
MAP annotated group
< key_type> MUST be STRING
< value_type> type of map values
MapType
"keyType" MUST be StringType
"valueType" is type of map values.
java.util.Map
Map
---
object
object
map
map< key_type, value_type>