Contraintes de type de champ XDM

Dans les schémas de modèle de données d’expérience (XDM), le type d’un champ restreint le type de données que le champ peut contenir. Ce document fournit un aperçu de chaque type de champ principal, y compris les autres formats de sérialisation auxquels ils peuvent être mappés et comment définir vos propres types de champ dans l’API afin d’appliquer différentes contraintes.

Prise en main

Avant d’utiliser ce guide, veuillez consulter la section principes de base de la composition des schémas pour une introduction aux schémas XDM, aux classes et aux groupes de champs de schéma.

Si vous prévoyez de définir vos propres types de champ dans l’API, il est vivement recommandé de commencer par la variable Guide de développement du registre des schémas pour savoir comment créer des groupes de champs et des types de données pour inclure vos champs personnalisés dans . Si vous utilisez l’interface utilisateur de l’Experience Platform pour créer vos schémas, consultez le guide sur la définition des champs dans l’interface utilisateur pour découvrir comment implémenter des contraintes sur les champs que vous définissez dans des groupes de champs personnalisés et des types de données.

Structure de base et exemples

XDM repose sur le schéma JSON. Par conséquent, les champs XDM héritent d’une syntaxe similaire lors de la définition de leur type. Comprendre comment différents types de champ sont représentés dans le schéma JSON peut aider à indiquer les contraintes de base de chaque type.

REMARQUE

Voir Guide de base des API pour plus d’informations sur le schéma JSON et d’autres technologies sous-jacentes dans les API Platform.

Le tableau suivant décrit la représentation de chaque type XDM dans le schéma JSON, ainsi qu’un exemple de valeur conforme au type :

Type XDM Schéma JSON Exemple
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
Court
{ "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"
Booléen
{"type": "string"}
true

*Toutes les chaînes au format date doivent être conformes à la norme ISO 8601 (RFC 3339, section 5.6).

Faire correspondre les types XDM à d’autres formats

Les sections ci-dessous décrivent comment chaque type XDM est mappé à d’autres formats de sérialisation courants :

IMPORTANT

Parmi les types XDM standard répertoriés dans les tableaux ci-dessous, la variable Carte est également inclus. Les cartes sont utilisées dans les schémas standard lorsque les données sont représentées sous la forme de clés qui mappent à certaines valeurs ou lorsque les clés ne peuvent pas raisonnablement être incluses dans un schéma statique et doivent être traitées comme des valeurs de données.

Les champs de type map sont réservés à l’utilisation des schémas du secteur et des fournisseurs et ne peuvent donc pas être utilisés dans les ressources personnalisées que vous définissez. L’inclusion du type de mappage dans les tableaux ci-dessous est uniquement destinée à vous aider à déterminer comment mapper vos données existantes à XDM si elles sont actuellement stockées dans l’un des formats répertoriés ci-dessous.

Parquet, Spark SQL et Java

Type XDM Parquet Spark SQL Java
Chaîne Type : BYTE_ARRAY
Annotation : UTF8
StringType java.lang.String
Double Type : DOUBLE LongType java.lang.Double
Long Type : INT64 LongType java.lang.Long
Entier Type : INT32
Annotation : INT_32
IntegerType java.lang.Integer
Court Type : INT32
Annotation : INT_16
ShortType java.lang.Short
Octet 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
Booléen Type : BOOLEAN BooleanType java.lang.Boolean
Carte MAP-groupe annoté

(<key-type> must STRING)
MapType

(keyType must StringType)
java.util.Map

Scala, .NET et CosmosDB

Type XDM Scala .NET CosmosDB
Chaîne String System.String String
Double Double System.Double Number
Long Long System.Int64 Number
Entier Int System.Int32 Number
Court Short System.Int16 Number
Octet Byte System.SByte Number
Date java.util.Date System.DateTime String
DateTime java.util.Date System.DateTime String
Booléen Boolean System.Boolean Boolean
Carte Map (N/A) object

MongoDB, Aerospike et Protobuf 2

Type XDM MongoDB Aerospike Protobuf 2
Chaîne string String string
Double double Double double
Long long Integer int64
Entier int Integer int32
Court int Integer int32
Octet int Integer int32
Date date Integer
(millisecondes Unix)
int64
(millisecondes Unix)
DateTime timestamp Integer
(millisecondes Unix)
int64
(millisecondes Unix)
Booléen bool Integer
(binaire 0/1)
bool
Carte object map map<key_type, value_type>

Définition des types de champ XDM dans l’API

Tous les champs XDM sont définis à l’aide de la norme Schéma JSON contraintes qui s’appliquent à leur type de champ, avec des contraintes supplémentaires pour les noms de champ qui sont appliquées par Experience Platform. L’API Schema Registry vous permet de définir des types de champ supplémentaires à l’aide de formats et de contraintes facultatives. Les types de champ XDM sont exposés par l’attribut field-level, meta:xdmType.

REMARQUE

meta:xdmType est une valeur générée par le système. Par conséquent, vous n’êtes pas obligé d’ajouter cette propriété au fichier JSON de votre champ lors de l’utilisation de l’API. La bonne pratique consiste à utiliser des types de schémas JSON (tels que string et integer) avec les contraintes min./max appropriées telles que définies dans le tableau ci-dessous.

Le tableau suivant décrit la mise en forme appropriée pour définir différents types de champs, y compris ceux avec des propriétés facultatives. Pour plus d’informations sur les propriétés facultatives et les mots-clés spécifiques au type, consultez la documentation des schémas JSON.

Pour commencer, recherchez le type de champ souhaité et utilisez l’exemple de code fourni pour créer votre requête API pour création d’un groupe de champs ou création d’un type de données.

Type XDM Propriétés facultatives Exemple
String
  • pattern
  • minLength
  • maxLength
"sampleField": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "maxLength": 2
}
URI
"sampleField": {
          "type": "string",
          "format": "uri"
}
Enum
  • default
  • meta:enum
Les valeurs d’énumération contraintes sont fournies sous la variable enum , tandis que des étiquettes facultatives destinées aux clients pour chaque valeur peuvent être fournies sous meta:enum:
"sampleField": {
          "type": "string",
          "enum": [
              "value1",
              "value2",
              "value3"
          ],
          "meta:enum": {
              "value1": "Value 1",
              "value2": "Value 2",
              "value3": "Value 3"
          },
          "default": "value1"
}

Notez que la variable meta:enum la valeur est not déclarer une énumération ou piloter toute validation de données par elle-même. Dans la plupart des cas, les chaînes fournies sous meta:enum sont également fournis sous enum pour s’assurer que les données sont limitées. Cependant, il existe certains cas d’utilisation où meta:enum est fourni sans qu’un enum tableau. Voir le tutoriel sur extension d’énumérations pour plus d’informations.
Number
"sampleField": {
          "type": "number"
}
Long
"sampleField": {
          "type": "integer",
          "minimum": -9007199254740992,
          "maximum": 9007199254740992
}
Integer
"sampleField": {
          "type": "integer",
          "minimum": -2147483648,
          "maximum": 2147483648
}
Court
"sampleField": {
          "type": "integer",
          "minimum": -32768,
          "maximum": 32768
}
Byte
"sampleField": {
          "type": "entier",
          "minimum": -128,
          "maximum": 128
  }
Booléen
  • 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 Tableau de types scalaires de base (par exemple, chaînes) :
"sampleField": {
          "type": "array",
          "items": {
            "type": "string"
  }
}
Un tableau d’objets défini par un autre schéma :
"sampleField": { "type": "array", "items" : { "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } }
Object Le type de chaque sous-champ défini sous properties peut être défini à l’aide de n’importe quel type scalaire :
"sampleField": {
          "type": "object",
          "properties": {
            "field1": {
              "type": "string"
            },
            "field2": {
              "type": "number"
    }
  }
}
Les champs de type objet peuvent être définis en référençant la variable $id d’un type de données :
"sampleField": { "type": "object", "$ref" : "https://ns.adobe.com/xdm/common/phoneinteraction" }
Map Une carte must not définissez les propriétés. It must définir une seule additionalProperties schéma pour décrire le type de valeurs contenues dans le mappage (chaque mappage ne peut contenir qu’un seul type de données). Les valeurs peuvent être tout XDM valide type ou une référence à un autre schéma à l’aide d’un $ref attribut.

Un champ map avec des valeurs de type chaîne :
"sampleField": {
          "type": "object",
          "additionalProperties":{
            "type": "string"
  }
}
Un champ map avec des tableaux de chaînes pour les valeurs :
"sampleField": {
          "type": "object",
          "additionalProperties":{
            "type": "array",
            "items": {
              "type": "string"
    }
  }
}
Un champ map qui fait référence à un autre type de données :
"sampleField": { "type": "object", "additionalProperties":{ "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } }

Sur cette page