Schema Registry APIでのXDM フィールドの定義
すべてのExperience Data Model （XDM）フィールドは、フィールドタイプに適用される標準のJSON Schema制約と、Adobe Experience Platformで適用されるフィールド名に対する追加の制約を使用して定義されます。 Schema Registry APIでは、形式とオプションの制約を使用して、スキーマ内のカスタムフィールドを定義できます。 XDM フィールドタイプは、フィールドレベルの属性meta:xdmTypeによって公開されます。
meta:xdmTypeはシステムで生成された値であるため、APIを使用する場合は、このプロパティをフィールドのJSONに追加する必要はありません（ カスタムマップタイプを作成する場合を除く）。 ベストプラクティスは、次の表で定義されている適切なmin/max制約を使用して、JSON スキーマタイプ（stringやintegerなど）を使用することです。このガイドでは、オプションのプロパティを含むさまざまなフィールドタイプを定義するための適切な書式設定について説明します。 オプションのプロパティとタイプ固有のキーワードに関する詳細については、JSON スキーマのドキュメントを参照してください。
最初に、目的のフィールドタイプを見つけ、提供されたサンプルコードを使用して、 フィールドグループの作成または データタイプの作成のAPI リクエストを構築します。
String string
String フィールドはtype: stringで示されます。
"sampleField": {
"title": "Sample String Field",
"description": "An example string field.",
"type": "string"
}
オプションとして、次の追加プロパティを使用して、文字列に入力できる値の種類を制限できます。
pattern：制約する正規表現パターン。minLength：文字列の最小長。 文字列は、デフォルトで1の最小値を受け取ります。maxLength：文字列の最大長。
"sampleField": {
"title": "Sample String Field",
"description": "An example string field with added constraints.",
"type": "string",
"pattern": "^[A-Z]{2}$",
"maxLength": 2
}
URI uri
URI個のフィールドはtype: stringによって示され、format プロパティはuriに設定されています。 他のプロパティは受け入れられません。
"sampleField": {
"title": "Sample URI Field",
"description": "An example URI field.",
"type": "string",
"format": "uri"
}
Enum enum
Enum フィールドではtype: stringを使用する必要があります。列挙値はenum配列で指定されます。
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
]
}
オプションとして、meta:enum プロパティの下の各値に顧客向けラベルを指定し、各ラベルをenumの下の対応する値にキー設定することができます。
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field with customer-facing labels.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
}
}
meta:enum値は、notが列挙を宣言するか、データ検証を単独で実行しません。 ほとんどの場合、meta:enumの下で指定された文字列もenumの下で提供され、データが制限されます。 ただし、対応するenum配列を指定せずにmeta:enumが指定される場合があります。 詳しくは、推奨値の定義に関するチュートリアルを参照してください。オプションでdefault プロパティを指定して、フィールドのデフォルト値enumを指定できます。 default プロパティは、JSON スキーマ仕様で定義された情報メタデータであり、Experience Platformの取り込み中またはデータ準備フロー中に自動的に適用されません。 UI🔗の タイプ固有のフィールドプロパティを参照してください。
"sampleField": {
"title": "Sample Enum Field",
"description": "An example enum field with customer-facing labels and a default value.",
"type": "string",
"enum": [
"value1",
"value2",
"value3"
],
"meta:enum": {
"value1": "Value 1",
"value2": "Value 2",
"value3": "Value 3"
},
"default": "value1"
}
default値が指定されておらず、列挙フィールドがrequiredに設定されている場合、このフィールドに対して受け入れられている値が欠落しているレコードは、取り込み時に検証に失敗します。Number number
数値フィールドはtype: numberで示され、その他の必須プロパティはありません。
"sampleField": {
"title": "Sample Number Field",
"description": "An example number field.",
"type": "number"
}
number型は、整数または浮動小数点数のいずれかの数値型に使用されます。一方、integer型は、特に整数型に使用されます。 各タイプのユースケースについて詳しくは、数値タイプに関するJSON スキーマのドキュメント を参照してください。Integer integer
Integer フィールドはtype: integerによって示され、他の必須フィールドはありません。
"sampleField": {
"title": "Sample Integer Field",
"description": "An example integer field.",
"type": "integer"
}
integer型は具体的には整数を指しますが、number型は任意の数値型（整数または浮動小数点数）に使用されます。 各タイプのユースケースについて詳しくは、数値タイプに関するJSON スキーマのドキュメント を参照してください。必要に応じて、定義にminimumおよびmaximum プロパティを追加することで、整数の範囲を制限できます。 スキーマビルダーUIでサポートされているその他の数値型は、Long、Short、Byteなど、特定のminimumおよびmaximumの制約を持つinteger型のみです。
"sampleField": {
"title": "Sample Integer Field",
"description": "An example integer field with added constraints.",
"type": "integer",
"minimum": 1,
"maximum": 100
}
Long long
スキーマビルダーUIを使用して作成されたLong フィールドと同等のフィールドは、特定のminimumとmaximumの値（-9007199254740992と9007199254740992）を持つinteger タイプのフィールド です。
"sampleField": {
"title": "Sample Long Field",
"description": "An example long field.",
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740992
}
Short short
スキーマビルダーUIを使用して作成されたShort フィールドと同等のフィールドは、特定のminimumとmaximumの値（-32768と32767）を持つinteger タイプのフィールド です。
"sampleField": {
"title": "Sample Short Field",
"description": "An example short field.",
"type": "integer",
"minimum": -32768,
"maximum": 32767
}
Byte byte
スキーマビルダーUIを使用して作成されたByte フィールドと同等のフィールドは、特定のminimumとmaximumの値（-128と127）を持つinteger タイプのフィールド です。
"sampleField": {
"title": "Sample Byte Field",
"description": "An example byte field.",
"type": "integer",
"minimum": -128,
"maximum": 127
}
Boolean boolean
Boolean フィールドはtype: booleanで示されます。
"sampleField": {
"title": "Sample Boolean Field",
"description": "An example boolean field.",
"type": "boolean"
}
必要に応じて、default プロパティを指定して、スキーマ定義で意図する値を文書化できます。 これはJSON スキーマのセマンティクスに従い、情報メタデータです。Experience Platformの取り込みとデータ準備のフローは、自動的にdefaultを適用しません。 UI🔗の タイプ固有のフィールドプロパティを参照してください。
"sampleField": {
"title": "Sample Boolean Field",
"description": "An example boolean field with a default value.",
"type": "boolean",
"default": false
}
default値が指定されておらず、ブール値フィールドがrequiredに設定されている場合、このフィールドの受け入れ可能な値が欠落しているレコードは、取り込み時に検証に失敗します。Date date
Date個のフィールドはtype: stringとformat: dateで示されます。 オプションでexamplesの配列を指定して、ユーザーがデータを手動で入力する際にサンプル日付文字列を表示する場合に活用することもできます。
"sampleField": {
"title": "Sample Date Field",
"description": "An example date field with an example array item.",
"type": "string",
"format": "date",
"examples": ["2004-10-23"]
}
DateTime date-time
DateTime個のフィールドはtype: stringとformat: date-timeで示されます。 また、オプションでexamplesの配列を指定して、ユーザーがデータを手動で入力する際にサンプルの日時文字列を表示する場合に活用することもできます。
"sampleField": {
"title": "Sample Datetime Field",
"description": "An example datetime field with an example array item.",
"type": "string",
"format": "date-time",
"examples": ["2004-10-23T12:00:00-06:00"]
}
Array array
Array フィールドは、type: arrayと、配列が受け入れる項目のスキーマを定義するitems オブジェクトによって示されます。
文字列の配列など、プリミティブ型を使用して配列項目を定義できます。
"sampleField": {
"title": "Sample Array Field",
"description": "An example array field using a primitive type.",
"type": "array",
"items": {
"type": "string"
}
}
$ref プロパティを使用してデータ型の$idを参照することで、既存のデータ型に基づいて配列項目を定義することもできます。 次はPayment Item オブジェクトの配列です。
"sampleField": {
"title": "Sample Array Field",
"description": "An example array field using a data type reference.",
"type": "array",
"items": {
"$ref": "https://ns.adobe.com/xdm/data/paymentitem"
}
}
Object object
Object フィールドは、type: objectと、スキーマフィールドのサブプロパティを定義するproperties オブジェクトによって示されます。
propertiesで定義された各サブフィールドは、任意のプリミティブ typeを使用するか、問題のデータタイプの$idを指す$ref プロパティを通じて既存のデータタイプを参照することで定義できます。
"sampleField": {
"title": "Sample Object Field",
"description": "An example object field.",
"type": "object",
"properties": {
"field1": {
"type": "string"
},
"field2": {
"$ref": "https://ns.adobe.com/xdm/common/measure"
}
}
}
問題のデータタイプがtype: objectとして定義されている場合、データタイプを参照してオブジェクト全体を定義することもできます。
"sampleField": {
"title": "Sample Object Field",
"description": "An example object field using a data type reference.",
"$ref": "https://ns.adobe.com/xdm/common/phoneinteraction"
}
Map map
マップフィールドは、基本的にobject タイプのフィールド で、制約のないキーのセットが含まれています。 オブジェクトと同様に、マップの値はtypeでobjectですが、そのmeta:xdmTypeは明示的にmapに設定されています。
マップ では、プロパティを定義することはできません。 マップ内に含まれる値のタイプを説明するために、単一のadditionalProperties スキーマを は 定義する必要があります（各マップには1つのデータタイプのみを含めることができます）。 typeの値はstringまたはintegerである必要があります。
例えば、文字列型の値を持つマップフィールドは、次のように定義されます。
"sampleField": {
"title": "Sample Map Field",
"description": "An example map field.",
"type": "object",
"meta:xdmType": "map",
"additionalProperties": {
"type": "string"
}
}
カスタムマップフィールドの作成について詳しくは、以下の節を参照してください。
カスタムマップタイプの作成 custom-maps
XDMで「マップのような」データを効率的にサポートするために、オブジェクトにmeta:xdmTypeをmapに設定して注釈を付け、キーセットが制約されていないようにオブジェクトを管理する必要があることを明確にすることができます。 マップフィールドに取り込むデータには、文字列キーと、文字列または整数値（additionalProperties.typeで決定）のみを使用する必要があります。
XDMでは、このストレージヒントの使用に次の制限を設けています。
- マップタイプは
object型である必要があります。 - マップタイプにはプロパティを定義しないでください（つまり、「空」オブジェクトを定義します）。
- マップタイプには、マップ内に配置される値を説明する
additionalProperties.typeフィールド（stringまたはinteger）を含める必要があります。
次のパフォーマンス上の問題があるため、絶対に必要な場合にのみマップタイプフィールドを使用してください。
- Adobe Experience Platform クエリサービス からの応答時間は、1億件のレコードに対して3秒から10秒に短縮されます。
- マップのキー数は16個未満である必要があります。そうでない場合、さらに劣化するリスクがあります。
Experience Platformのユーザーインターフェイスには、マップタイプフィールドのキーを抽出する方法にも制限があります。 オブジェクトタイプのフィールドは拡張できますが、マップは単一のフィールドとして表示されます。
次の手順
このガイドでは、APIでさまざまなフィールドタイプを定義する方法について説明しました。 XDM フィールドタイプのフォーマット方法について詳しくは、XDM フィールドタイプの制約に関するガイドを参照してください。