Mapping sets endpoint
Mapping sets can be used to define how data in a source schema maps to that of a destination schema. You can use the /mappingSets
endpoint in the Data Prep API to programmatically retrieve, create, update, and validate mapping sets.
List mapping sets
You can retrieve a list of all the mapping sets for your organization by making a GET request to the /mappingSets
endpoint.
API format
The /mappingSets
endpoint supports several query parameters to help filter your results. While most of these parameters are optional, their use is strongly recommended to help reduce expensive overhead. However, you must include both the start
and limit
parameters as part of your request. Multiple parameters can be included, separated by ampersands (&
).
GET /mappingSets?limit={LIMIT}&start={START}
GET /mappingSets?limit={LIMIT}&start={START}&name={NAME}
GET /mappingSets?limit={LIMIT}&start={START}&orderBy={ORDER_BY}
GET /mappingSets?limit={LIMIT}&start={START}&expandSchema={EXPAND_SCHEMA}
{LIMIT}
{START}
start=0
.{NAME}
{ORDER_BY}
createdDate
and updatedDate
. You can prepend the property with +
or -
to sort it by ascending or descending order respectively.{EXPAND_SCHEMA}
Request
The following request will retrieve the last two mapping sets within your organization.
curl -X GET https://platform.adobe.io/data/foundation/conversion/mappingSets?limit=2&start=0 \
-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}'
Response
{
"data": [
{
"id": "428beb15b4864daaaa9dc3f005448005",
"version": 1,
"createdDate": 1582250953000,
"modifiedDate": 1582251156000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_ui_platform",
"supportVersion": "1.1",
"inputSchema": {
"id": "e660142cab8e438382abc5691b364b30",
"version": 0,
"sampleId": "f9e83882e3e34c1f8b873a3b8113c01e"
},
"outputSchema": {
"id": "1956affc28be468aa452e5e47c680c6b",
"version": 0,
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
}
},
"mappings": [
{
"id": "af809223484341009ce0db13d4b32a3a",
"version": 0,
"createdDate": 1582250953000,
"modifiedDate": 1582250953000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_xql_gateway",
"sourceType": "text/x.schema-path",
"source": "id",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "id",
"destinationXdmPath": "person.name.firstName"
}
],
"status": "PUBLISHED",
"strictMapping": false,
"allowNullValues": false,
"xdmVersion": "1.0",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
},
"xdmSchema": "https://ns.adobe.com/xdm/context/profile__union"
},
{
"id": "8afb1351833a4a4692ea61074b60813b",
"version": 0,
"createdDate": 1582250893000,
"modifiedDate": 1582250893000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_xql_gateway",
"supportVersion": "1.1",
"inputSchema": {
"id": "97fe2ecf4faa400bb66dd6be88a53fe4",
"version": 0,
"sampleId": "0248bfb352214f908bdd6cf9c19447e1"
},
"outputSchema": {
"id": "e9c3696715d94905bb4e9bfc2c508e66",
"version": 0,
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
}
},
"mappings": [
{
"id": "74647d8bf3b742f289534bee2fdeb732",
"version": 0,
"createdDate": 1582250893000,
"modifiedDate": 1582250893000,
"createdBy": "acp_xql_gateway",
"modifiedBy": "acp_xql_gateway",
"sourceType": "text/x.schema-path",
"source": "last_name",
"destination": "person.name.lastName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "last_name",
"destinationXdmPath": "person.name.lastName"
}
],
"status": "DRAFT",
"strictMapping": false,
"allowNullValues": false,
"xdmVersion": "1.0",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "1.0"
},
"xdmSchema": "https://ns.adobe.com/xdm/context/profile__union"
}
],
"_page": {
"count": 0,
"limit": 2
}
}
Create a mapping set
You can create a new mapping set by making a POST request to the /mappingSets
endpoint.
API format
POST /mappingSets
Request
The following request creates a new mapping set, configured by the parameters provided in the payload.
curl -X POST https://platform.adobe.io/data/foundation/conversion/mappingSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{
"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
]
}
outputSchema.schemaRef.id
outputSchema.schemaRef.contentType
mappings.sourceType
The source type describes how the value will be extracted from the source to the destination. The source type supports two possible values:
ATTRIBUTE
: The source typeATTRIBUTE
is used when the input attribute is from a source schema.EXPRESSION
: The source typeEXPRESSION
is used when mapping is completed using a calculated field.
WARNING: Incorrectly setting the source type values can render your mapping sets uneditable.
mappings.source
mappings.destination
Response
A successful response returns HTTP status 200 with information about your newly created mapping set.
{
"id": "e7c80e4c0d8f4a98a7d400b4e178b635",
"version": 0,
"createdDate": 1614901254724,
"modifiedDate": 1614901254724,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Validate mappings
You can validate that your mappings properly work by making a POST request to the /mappingSets/validate
endpoint.
API format
POST /mappingSets/validate
Request
The following request validates the mappings provided in the payload.
curl -X POST https://platform.adobe.io/data/foundation/conversion/mappingSets/validate \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{
"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
]
}
Response
A successful response returns HTTP status 200 with validation information for the proposed mapping.
{
"validationResponse": [
{
"status": "SUCCESS",
"errors": null
},
{
"status": "SUCCESS",
"errors": null
},
{
"status": "SUCCESS",
"errors": null
}
]
}
Preview data for mappings
You can preview what your data will be mapped to by making a POST request to the /mappingSets/preview
endpoint.
API format
POST /mappingSets/preview
Request
curl -X POST https://platform.adobe.io/data/foundation/conversion/mappingSets/preview \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"data": [
{
"id": 1234,
"firstName": "Jim",
"lastName": "Seltzer"
}
],
"mappingSet": {
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/stardust/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{
"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
}
]
}
}'
Response
A successful response returns HTTP status 200 with a preview of your mapped data.
[
{
"data": {
"person": {
"name": {
"firstName": "Jim",
"lastName": "Seltzer"
}
},
"_id": "1234"
},
"errors": null
}
]
Look up a mapping set
You can retrieve a specific mapping set by providing its ID in the path of a GET request to the /mappingSets
endpoint. This endpoint also supports several query parameters to help you retrieve details about the specified mapping set version.
API format
GET /mappingSets/{MAPPING_SET_ID}
GET /mappingSets/{MAPPING_SET_ID}?expandSchema={EXPAND_SCHEMA}
GET /mappingSets/{MAPPING_SET_ID}?version={VERSION}
{MAPPING_SET_ID}
{EXPAND_SCHEMA}
{VERSION}
Request
The following request retrieves detailed information about a specified mapping set.
curl -X GET https://platform.adobe.io/data/foundation/conversion/mappingSets/e7c80e4c0d8f4a98a7d400b4e178b635 \
-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}'
Response
A successful response returns HTTP status 200 with detailed information about the mapping set you wanted to retrieve.
{
"id": "e7c80e4c0d8f4a98a7d400b4e178b635",
"version": 0,
"createdDate": 1614901255000,
"modifiedDate": 1614901255000,
"createdBy": "CAEB5DE75E6FBFAC0A494110@techacct.adobe.com",
"modifiedBy": "CAEB5DE75E6FBFAC0A494110@techacct.adobe.com",
"supportVersion": "1.1",
"outputSchema": {
"id": "cf0a57df22354cfdb5f32a747b63a456",
"version": 0,
"jsonSchema": {
"title": "A sample schema",
"description": "My sample schema",
"type": "object",
"properties": {
"_id": {
"title": "Identifier",
"description": "A unique identifier for the record.",
"type": "string"
},
"_repo": {
"type": "object",
"properties": {
"createDate": {
"type": "string",
"format": "date-time"
},
"modifyDate": {
"type": "string",
"format": "date-time"
}
}
},
"createdByBatchID": {
"type": "string",
"format": "uri-reference"
},
"modifiedByBatchID": {
"type": "string",
"format": "uri-reference"
},
"person": {
"type": "object",
"properties": {
"birthDate": {
"type": "string",
"format": "date"
},
"birthDayAndMonth": {
"type": "string",
"pattern": "[0-1][0-9]-[0-9][0-9]"
},
"birthYear": {
"type": "integer",
"minimum": 1,
"maximum": 32767
},
"gender": {
"type": "string",
"default": "not_specified",
"enum": [
"non_specific",
"not_specified",
"female",
"male"
]
},
"name": {
"title": "Full name",
"description": "The person's full name.",
"type": "object",
"properties": {
"firstName": {
"title": "First name",
"type": "string"
},
"fullName": {
"title": "Full name",
"type": "string"
},
"lastName": {
"title": "Last name",
"type": "string"
},
"middleName": {
"title": "Middle name",
"type": "string"
}
}
}
}
},
"personID": {
"title": "Person ID",
"type": "string"
},
"repositoryCreatedBy": {
"title": "Created by user identifier",
"type": "string"
},
"repositoryLastModifiedBy": {
"title": "Modified by user identifier",
"type": "string"
}
},
"version": "1.0",
"imsOrg": "{ORG_ID}",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305"
},
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"id": "a11f44b0214d4fdcb79cbb5e1d93e638",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"id": "b9bf7873451f4b7ba767ca3ba9327750",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName",
},
{
"id": "bab961fc18f54789b9268ec04c6f6f9b",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "lastName",
"destination": "person.name.lastName",
}
],
"status": "DRAFT",
"strictMapping": false,
"allowNullValues": false,
"xdmVersion": "application/vnd.adobe.xed-full+json;version=1",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305"
}
Update a mapping set
You can update a mapping set by providing its ID in the path of a PUT
request to the mappingSets
endpoint.
API format
PUT /mappingSets/{MAPPING_SET_ID}
{MAPPING_SET_ID}
Request
curl -X PUT https://platform.adobe.io/data/foundation/conversion/mappingSets/e7c80e4c0d8f4a98a7d400b4e178b635 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"sourceType": "ATTRIBUTE",
"source": "firstName",
"destination": "person.name.firstName"
},
{
"sourceType": "ATTRIBUTE",
"source": "lastName",
"destination": "person.name.lastName"
},
{
"sourceType": "ATTRIBUTE",
"source": "nationality",
"destination": "person.nationality"
}
]
}
Response
A successful response returns HTTP status 200 with detailed information about your newly updated mapping set.
{
"id": "e7c80e4c0d8f4a98a7d400b4e178b635",
"version": 1,
"createdDate": 1614901255000,
"modifiedDate": 1614909614227,
"createdBy": "CAEB5DE75E6FBFAC0A494110@techacct.adobe.com",
"modifiedBy": "CAEB5DE75E6FBFAC0A494110@techacct.adobe.com",
"supportVersion": "1.1",
"outputSchema": {
"id": "cf0a57df22354cfdb5f32a747b63a456",
"version": 0,
"jsonSchema": {
"title": "A sample schema",
"description": "My sample schema",
"type": "object",
"properties": {
"_id": {
"title": "Identifier",
"description": "A unique identifier for the record.",
"type": "string",
},
"_repo": {
"type": "object",
"properties": {
"createDate": {
"type": "string",
"format": "date-time"
},
"modifyDate": {
"type": "string",
"format": "date-time"
}
}
},
"createdByBatchID": {
"type": "string",
"format": "uri-reference"
},
"modifiedByBatchID": {
"type": "string",
"format": "uri-reference"
},
"person": {
"type": "object",
"properties": {
"birthDate": {
"type": "string",
"format": "date"
},
"birthDayAndMonth": {
"type": "string",
"pattern": "[0-1][0-9]-[0-9][0-9]"
},
"birthYear": {
"type": "integer",
"minimum": 1,
"maximum": 32767
},
"gender": {
"type": "string",
"default": "not_specified",
"enum": [
"non_specific",
"not_specified",
"female",
"male"
]
},
"name": {
"title": "Full name",
"description": "The person's full name.",
"type": "object",
"properties": {
"firstName": {
"title": "First name",
"type": "string"
},
"fullName": {
"title": "Full name",
"type": "string"
},
"lastName": {
"title": "Last name",
"type": "string"
},
"middleName": {
"title": "Middle name",
"type": "string"
},
"suffix": {
"title": "Suffix",
"type": "string"
}
}
}
},
"personID": {
"title": "Person ID",
"type": "string"
},
"repositoryCreatedBy": {
"title": "Created by user identifier",
"type": "string"
},
"repositoryLastModifiedBy": {
"title": "Modified by user identifier",
"type": "string"
}
},
"version": "1.0",
"imsOrg": "6A29340459CA8D350A49413A@AdobeOrg",
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305"
},
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"id": "1bb13ec5929f4847a8ea0f1d9e60d3e6",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "id",
"destination": "_id",
"name": "id"
},
{
"id": "394bec970d54410b98e1d4c55a3843ca",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName"
},
{
"id": "a78729629b22418998b528755b3e0fb1",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "lastName",
"destination": "person.name.lastName"
},
{
"id": "c5211e1e295f48018c125c24a04e925a",
"version": 0,
"sourceType": "text/x.schema-path",
"source": "nationality",
"destination": "person.nationality"
}
],
"strictMapping": false,
"allowNullValues": false,
"xdmVersion": "application/vnd.adobe.xed-full+json;version=1",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/89abc189258b1cb1a816d8f2b2341a6d98000ed8f4008305"
}
List the mappings for a mapping set
You can view all the mappings that belong to a specific mapping set by providing its ID in the path of a GET request to the following endpoint.
API format
GET /mappingSets/{MAPPING_SET_ID}/mappings
{MAPPING_SET_ID}
Request
The following request returns all the mappings in the specified mapping set.
curl -X GET https://platform.adobe.io/data/foundation/conversion/mappingSets/e7c80e4c0d8f4a98a7d400b4e178b635/mappings \
-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}'
Response
[
{
"id": "1bb13ec5929f4847a8ea0f1d9e60d3e6",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "id",
"destination": "_id",
"name": "id",
"description": "Identifier field",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "id",
"destinationXdmPath": "_id"
},
{
"id": "394bec970d54410b98e1d4c55a3843ca",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "firstName",
"destinationXdmPath": "person.name.firstName"
},
{
"id": "a78729629b22418998b528755b3e0fb1",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "lastName",
"destination": "person.name.lastName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "lastName",
"destinationXdmPath": "person.name.lastName"
},
{
"id": "c5211e1e295f48018c125c24a04e925a",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "nationality",
"destination": "person.nationality",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "nationality",
"destinationXdmPath": "person.nationality"
}
]
Look up a mapping within a mapping set
You can retrieve a specific mapping for a mapping set by providing their IDs in the path of a GET request to the following endpoint.
API format
GET /mappingSets/{MAPPING_SET_ID}/mappings/{MAPPING_ID}
{MAPPING_SET_ID}
{MAPPING_ID}
Request
The following request retrieves information about a specific mapping in the specified mapping set.
curl -X GET https://platform.adobe.io/data/foundation/conversion/mappingSets/e7c80e4c0d8f4a98a7d400b4e178b635/mappings/394bec970d54410b98e1d4c55a3843ca \
-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}'
Response
A successful response returns HTTP status 200 with detailed information about the specified mapping.
{
"id": "394bec970d54410b98e1d4c55a3843ca",
"version": 0,
"createdDate": 1614909614000,
"modifiedDate": 1614909614000,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceType": "text/x.schema-path",
"source": "firstName",
"destination": "person.name.firstName",
"identity": false,
"primaryIdentity": false,
"matchScore": 0.0,
"functionVersion": 1,
"sourceAttribute": "firstName",
"destinationXdmPath": "person.name.firstName"
}