Experience Platform API fundamentals

Adobe Experience Platform APIs employ several underlying technologies and syntaxes that are important to understand in order to effectively manage JSON-based Platform resources. This document provides a brief overview of these technologies, as well as links to external documentation for more information.

JSON Pointer json-pointer

JSON Pointer is a standardized string syntax (RFC 6901) for identifying specific values within JSON documents. A JSON Pointer is a string of tokens separated by / characters, which specify either object keys or array indexes, and the tokens can be a string or a number. JSON Pointer strings are used in many PATCH operations for Platform APIs, as described later in this document. For more information on JSON Pointer, please refer to the JSON Pointer overview documentation.

Example JSON schema object

The following JSON represents a simplified XDM schema whose fields can be referenced using JSON Pointer strings. Note that all fields that have been added using custom schema field groups (such as loyaltyLevel) are namespaced under a _{TENANT_ID} object, whereas fields that have been added using core field groups (such as fullName) are not.

{
  "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/85a4bdaa168b01bf44384e049fbd3d2e9b2ffaca440d35b9",
  "meta:altId": "_{TENANT_ID}.schemas.85a4bdaa168b01bf44384e049fbd3d2e9b2ffaca440d35b9",
  "meta:resourceType": "schemas",
  "version": "1.0",
  "title": "Example schema",
  "type": "object",
  "description": "This is an example schema.",
  "properties": {
    "_{TENANT_ID}": {
      "type": "object",
      "properties": {
        "loyaltyLevel": {
          "title": "Loyalty Level",
          "description": "",
          "type": "string",
          "isRequired": false,
          "enum": [
            "platinum",
            "gold",
            "silver",
            "bronze"
          ]
        }
      }
    },
    "person": {
      "title": "Person",
      "description": "An individual actor, contact, or owner.",
      "type": "object",
      "properties": {
        "name": {
          "title": "Full name",
          "description": "The person's full name.",
          "type": "object",
          "properties": {
            "fullName": {
              "title": "Full name",
              "type": "string",
              "description": "The full name of the person, in writing order most commonly accepted in the language of the name.",
            },
            "suffix": {
              "title": "Suffix",
              "type": "string",
              "description": "A group of letters provided after a person's name to provide additional information. The `suffix` is used at the end of someones name. For example Jr., Sr., M.D., PhD, I, II, III, etc.",
            }
          },
          "meta:referencedFrom": "https://ns.adobe.com/xdm/context/person-name",
          "meta:xdmField": "xdm:name"
        }
      }
    }
  }
}

Example JSON Pointers based on schema object

JSON Patch json-patch

There are many PATCH operations for Platform APIs that accept JSON Patch objects for their request payloads. JSON Patch is a standardized format (RFC 6902) for describing changes to a JSON document. It allows you to define partial updates to JSON without needing to send the entire document in a request body.

Example JSON Patch object

{
  "op": "remove",
  "path": "/foo"
}

Depending on the operation type indicated in op, the JSON Patch object may require additional properties. For more information on the different JSON Patch operations and their required syntax, please refer to the JSON Patch documentation.

JSON Schema json-schema

JSON Schema is a format used to describe and validate the structure of JSON data. Experience Data Model (XDM) leverages JSON Schema capabilities to enforce constraints on the structure and format of ingested customer experience data. For more information on JSON Schema, please refer to the official documentation.

Next steps

This document introduced some of the technologies and syntaxes involved with managing JSON-based resources for Experience Platform. Refer to the getting started guide for more information on working with Platform APIs, including best practices. For answers to frequently asked questions, refer to the Platform troubleshooting guide.