Unions (or union views) are system-generated, read-only schemas that aggregate the fields of all schemas which share the same class (XDM ExperienceEvent or XDM Individual Profile) and are enabled for Real-Time Customer Profile.
This document covers essential concepts for working with unions in the Schema Registry API, including sample calls for various operations. For more general information about unions in XDM, see the section on unions in the basics of schema composition.
The Schema Registry automatically includes three key fields within a union schema: identityMap
, timeSeriesEvents
, and segmentMembership
.
A union schema’s identityMap
is a representation of the known identities within the union’s associated record schemas. The identity map separates identities into different arrays keyed by namespace. Each listed identity is itself an object containing a unique id
value. See the Identity Service documentation for more information.
The timeSeriesEvents
array is a list of time-series events that relate to the record schemas that are associated with the union. When profile data is exported to datasets, this array is included for each record. This is useful for various use-cases, such as machine learning where models need a profile’s entire behavior history in addition to its record attributes.
The segmentMembership
map stores the results of evaluating a segment definition. When segment jobs are successfully run using the Segmentation API, the map is updated. segmentMembership
also stores any pre-evaluated audiences that are ingested into Platform, allowing for integration with other solutions like Adobe Audience Manager. See the tutorial on creating audiences using APIs for more information.
When you set the union
tag on a schema, the Schema Registry automatically adds the schema to the union for the class upon which the schema is based. If no union exists for the class in question, a new union is automatically created. The $id
for the union is similar to the standard $id
of other Schema Registry resources, with the only difference being that is appended by two underscores and the word “union” (__union
).
You can view a list of available unions by making GET request to the /tenant/unions
endpoint.
API format
GET /tenant/unions
Request
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xed-id+json'
The response format depends on the Accept
header sent in the request. The following Accept
headers are available for listing unions:
Accept header |
Description |
---|---|
application/vnd.adobe.xed-id+json |
Returns a short summary of each resource. This is the recommended header for listing resources. (Limit: 300) |
application/vnd.adobe.xed+json |
Returns full JSON class for each resource, with original $ref and allOf included. (Limit: 300) |
Response
A successful response returns HTTP status 200 (OK) and a results
array in the response body. If unions have been defined, the details for each union are provided as objects within the array. If no unions have been defined, HTTP status 200 (OK) is still returned but the results
array will be empty.
{
"results": [
{
"title": "XDM Individual Profile",
"$id": "https://ns.adobe.com/xdm/context/profile__union",
"meta:altId": "_xdm.context.profile__union",
"version": "1"
},
{
"title": "Property",
"$id": "https://ns.adobe.com/{TENANT_ID}/classes/19e1d8b5098a7a76e2c10a81cbc99590__union",
"meta:altId": "_{TENANT_ID}.classes.19e1d8b5098a7a76e2c10a81cbc99590__union",
"version": "1"
}
]
}
You can view a specific union by performing a GET request that includes the $id
and, depending on the Accept header, some or all of the details of the union.
Union lookups are available using the /unions
and /schemas
endpoint to enable them for use in Profile exports into a dataset.
API format
GET /tenant/unions/{UNION_ID}
GET /tenant/schemas/{UNION_ID}
Parameter | Description |
---|---|
{UNION_ID} |
The URL-encoded $id URI of the union you want to look up. URIs for union schemas are appended with “__union”. |
Request
curl -X GET \
https://platform.adobe.io/data/foundation/schemaregistry/tenant/unions/https%3A%2F%2Fns.adobe.com%2Fxdm%2Fcontext%2Fprofile__union \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Accept: application/vnd.adobe.xed+json; version=1'
Union lookup requests require a version
be included in the Accept header.
The following Accept headers are available for union schema lookups:
Accept | Description |
---|---|
application/vnd.adobe.xed+json; version=1 |
Raw with $ref and allOf . Includes titles and descriptions. |
application/vnd.adobe.xed-full+json; version=1 |
$ref attributes and allOf resolved. Includes titles and descriptions. |
Response
A successful response returns the union view of all schemas that implement the class whose $id
was provided in the request path.
The response format depends on the Accept header sent in the request. Experiment with different Accept headers to compare the responses and determine which header is best for your use case.
{
"type": "object",
"description": "Union view of all schemas that extend https://ns.adobe.com/xdm/context/profile",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/context/identitymap",
"https://ns.adobe.com/xdm/common/extensible",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/{TENANT_ID}/mixins/477bb01d7125b015b4feba7bccc2e599",
"https://ns.adobe.com/xdm/context/profile-personal-details"
],
"title": "Union object for https://ns.adobe.com/xdm/context/profile",
"$id": "https://ns.adobe.com/xdm/context/profile__union",
"meta:containerId": "tenant",
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:altId": "_xdm.context.profile__union",
"version": "1.0",
"meta:resourceType": "unions",
"meta:registryMetadata": {}
}
In order for a schema to be included in the union for its class, a union
tag must be added to the schema’s meta:immutableTags
attribute. You can accomplish this by making a PATCH request to add an meta:immutableTags
array with a single string value of union
to the schema in question. See the schemas endpoint guide for a detailed example.
In order to see which schemas are part of a specific union, you can perform a GET request to the /tenant/schemas
endpoint. Using the property
query parameter, you can configure the response to only return schemas containing a meta:immutableTags
field and a meta:class
equal to the class whose union you are accessing.
API Format
GET /tenant/schemas?property=meta:immutableTags==union&property=meta:class=={CLASS_ID}
Parameter | Description |
---|---|
{CLASS_ID} |
The $id of the class whose union-enabled schemas you want to list. |
Request
The following request retrieves a list of all schemas that are part of the union for the XDM Individual Profile class.
curl -X GET \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile' \
-H 'Accept: application/vnd.adobe.xed-id+json' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
The response format depends on the Accept
header sent in the request. The following Accept
headers are available for listing schemas:
Accept header |
Description |
---|---|
application/vnd.adobe.xed-id+json |
Returns a short summary of each resource. This is the recommended header for listing resources. (Limit: 300) |
application/vnd.adobe.xed+json |
Returns full JSON schema for each resource, with original $ref and allOf included. (Limit: 300) |
Response
A successful response returns a filtered list of schemas, containing only those that belong to the specified class which have been enabled for union membership. Remember that when using multiple query parameters, an AND relationship is assumed.
{
"results": [
{
"title": "Schema 1",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/142afb78d8b368a5ba97a6cc8fc7e033",
"meta:altId": "_{TENANT_ID}.schemas.142afb78d8b368a5ba97a6cc8fc7e033",
"version": "1.2"
},
{
"title": "Schema 2",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e7297a6ddfc7812ab3a7b504a1ab98da",
"meta:altId": "_{TENANT_ID}.schemas.e7297a6ddfc7812ab3a7b504a1ab98da",
"version": "1.5"
},
{
"title": "Schema 3",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/50f960bb810e99a21737254866a477bf",
"meta:altId": "_{TENANT_ID}.schemas.50f960bb810e99a21737254866a477bf",
"version": "1.2"
},
{
"title": "Schema 4",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/a39655ca8ea3d5c1f36a463b45fccca8",
"meta:altId": "_{TENANT_ID}.schemas.a39655ca8ea3d5c1f36a463b45fccca8",
"version": "1.1"
},
{
"title": "Schema 5",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/c063fac45c6d6285ef33b0e2af09f633",
"meta:altId": "_{TENANT_ID}.schemas.c063fac45c6d6285ef33b0e2af09f633",
"version": "1.2"
},
{
"title": "Schema 6",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/dfebb19b93827b70bbad006137812537",
"meta:altId": "_{TENANT_ID}.schemas.dfebb19b93827b70bbad006137812537",
"version": "1.7"
}
],
"_links": {
"global_schemas": {
"href": "https://platform.adobe.io/data/foundation/schemaregistry/global/schemas?property=meta:immutableTags==union&property=meta:class==https://ns.adobe.com/xdm/context/profile"
}
}
}