Getting started with the Schema Registry API

The Schema Registry API allows you to create and manage various Experience Data Model (XDM) resources. This document provides an introduction to the core concepts you need to know before attempting to make calls to the Schema Registry API.

Prerequisites

Using the developer guide requires a working understanding of the following components of Adobe Experience Platform:

XDM uses JSON Schema formatting to describe and validate the structure of ingested customer experience data. It is therefore strongly recommended that you review the official JSON Schema documentation for a better understanding of this underlying technology.

Reading sample API calls

The Schema Registry API documentation provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Gather values for required headers

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform, including those belonging to the Schema Registry, are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All lookup (GET) requests to the Schema Registry require an additional Accept header, whose value determines the format of information returned by the API. See the Accept header section below for more details.

All requests that contain a payload (POST, PUT, PATCH) require an additional header:

Know your TENANT_ID know-your-tenant_id

Throughout the API guides you will see references to a TENANT_ID. This ID is used to ensure that resources you create are namespaced properly and contained within your organization. If you do not know your ID, you can access it by performing the following GET request:

API format

GET /stats

Request

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/stats \
  -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 information regarding your organization’s use of the Schema Registry. This includes a tenantId attribute, the value of which is your TENANT_ID.

{
  "imsOrg":"{ORG_ID}",
  "tenantId":"{TENANT_ID}",
  "counts": {
    "schemas": 4,
    "mixins": 3,
    "datatypes": 1,
    "classes": 2,
    "unions": 0,
  },
  "recentlyCreatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:created": "Sat Feb 02 2019 00:24:30 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "$id": "https://ns.adobe.com/{TENANT_ID}/classes/5bdb5582be0c0f3ebfc1c603b705764f",
      "title": "Tenant Class",
      "description": "Tenant Defined Class",
      "meta:resourceType": "classes",
      "meta:created": "Fri Feb 01 2019 22:46:21 GMT+0000 (UTC)",
      "version": "1.0"
    }
  ],
  "recentlyUpdatedResources": [
    {
      "title": "Sample Field Group",
      "description": "New Sample Field Group.",
      "meta:resourceType": "mixins",
      "meta:updated": "Sat Feb 02 2019 00:34:06 GMT+0000 (UTC)",
      "version": "1.1"
    },
    {
      "title": "Data Schema",
      "description": "Schema for Data Information",
      "meta:resourceType": "schemas",
      "meta:updated": "Fri Feb 01 2019 23:47:43 GMT+0000 (UTC)",
      "meta:class": "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab",
      "meta:classTitle": "Sample Class",
      "version": "1.1"
    }
 ],
 "classUsage": {
    "https://ns.adobe.com/{TENANT_ID}/classes/47b2189fc135e03c844b4f25139d10ab": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
        "title": "Tenant Data Schema",
        "description": "Schema for tenant-specific data."
      }
    ],
    "https://ns.adobe.com/xdm/context/profile": [
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/3ac6499f0a43618bba6b138226ae3542",
        "title": "Simple Profile",
        "description": "A simple profile schema."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
        "title": "Program Schema",
        "description": "Schema for program-related data."
      },
      {
        "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/4025a705890c6d4a4a06b16f8cf6f4ca",
        "title": "Sample Schema",
        "description": "A sample schema."
      }
    ]
  }
 }

Understand the CONTAINER_ID container

Calls to the Schema Registry API require the use of a CONTAINER_ID. There are two containers against which API calls can be made: the global container and the tenant container.

Global container

The global container holds all standard Adobe and Experience Platform partner provided classes, schema field groups, data types, and schemas. You may only perform list and lookup (GET) requests against the global container.

An example of a call that uses the global container would look like the following:

GET /global/classes

Tenant container

Not to be confused with your unique TENANT_ID, the tenant container holds all classes, field groups, data types, schemas, and descriptors defined by an organization. These are unique to each organization, meaning they are not visible or manageable by other organizations. You may perform all CRUD operations (GET, POST, PUT, PATCH, DELETE) against resources that you create in the tenant container.

An example of a call that uses the tenant container would look like the following:

POST /tenant/fieldgroups

When you create a class, field group, schema or data type in the tenant container, it is saved to the Schema Registry and assigned an $id URI that includes your TENANT_ID. This $id is used throughout the API to reference specific resources. Examples of $id values are provided in the next section.

Resource identification resource-identification

XDM resources are identified with an $id attribute in the form of a URI, such as the following examples:

To make the URI more REST-friendly, schemas also have a dot-notation encoding of the URI in a property called meta:altId:

Calls to the Schema Registry API will support either the URL-encoded $id URI or the meta:altId (dot-notation format). Best practice is to use the URL-encoded $id URI when making a REST call to the API, like so:

Accept header accept

When performing list and lookup (GET) operations in the Schema Registry API, an Accept header is required to determine the format of the data returned by the API. When looking up specific resources, a version number must also be included in the Accept header.

The following table lists compatible Accept header values, including those with version numbers, along with descriptions of what the API will return when they are used.

Schema versioning versioning

Schema versions are referenced by Accept headers in the Schema Registry API and in schemaRef.contentType properties in downstream Platform service API payloads.

Currently, Platform only supports a single major version (1) for each schema. According to the rules of schema evolution, each update to a schema must be non-destructive, meaning that new minor versions of a schema (1.2, 1.3, etc.) are always backward compatible with previous minor versions. Therefore, when specifying version=1, the Schema Registry always returns the latest major version 1 of a schema , meaning that previous minor versions are not returned.

XDM field constraints and best practices

The fields of a schema are listed within its properties object. Each field is itself an object, containing attributes to describe and constrain the data that the field can contain. Refer to the guide on defining custom fields in the API for code samples and optional constraints for the most commonly used data types.

The following sample field illustrates a properly formatted XDM field, with further details on naming constraints and best practices provided below. These practices can also be applied when defining other resources that contain similar attributes.

"fieldName": {
    "title": "Field Name",
    "type": "string",
    "format": "date-time",
    "examples": [
        "2004-10-23T12:00:00-06:00"
    ],
    "description": "Full sentence describing the field, using proper grammar and punctuation.",
}

Next steps

To begin making calls using the Schema Registry API, select one of the available endpoint guides.