APL Data Sources and Transformers (APL 1.1 and 1.2)

(This is not the most recent version of APL. Use the Other Versions option to see the documentation for the most recent version of APL)

A data source is a JSON structure that defines a source of data you can bind to an APL document. When you send an APL document to Alexa, you can include one or more data sources. The data sources are bound by name into the APL document's parameters. APL components within the document can then reference those data sources using a data-binding expression.

Datasources object in the skill response

You pass a data source to Alexa in a datasources object that is part of the RenderDocument directive, but outside of the APL document itself. This datasources object can only contain other objects (the actual data sources).

This example shows a skill response with the RenderDocument directive. It passes the document and a data source named "myDocumentData". The document content is omitted for brevity:

{
  "version": "1.0",
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>This is a sample</speak>"
    },
    "sessionAttributes": {},
    "directives": [
      {
        "type": "Alexa.Presentation.APL.RenderDocument",
        "token": "[SkillProvidedToken]",
        "document": {},
        "datasources": {
          "myDocumentData": {
            "title": "This is a very simple sample"
          }
        }
      }
    ]
  }
}

Access the data source in the document

To access a data source, the APL document's mainTemplate declares a parameter called payload. This parameter is assigned to the root of the datasources object in the response. Therefore, from within the document, you can bind a property in your document to a property in the data source with the syntax ${payload.dataSourceName.propertyName}.

The following response demonstrates an APL document that binds to a single data source called myDocumentData. In this case, the text property of the Text component is bound to the title property of the myDocumentData data source. When your skill sends this response to Alexa, the device displays the text "This is a very simple sample".

{
  "version": "1.0",
  "sessionAttributes": {},
  "response": {
    "outputSpeech": {
      "type": "SSML",
      "ssml": "<speak>This is a sample</speak>"
    },
    "directives": [
      {
        "type": "Alexa.Presentation.APL.RenderDocument",
        "token": "[SkillProvidedToken]",
        "document": {
          "type": "APL",
          "version": "2024.3",
          "theme": "auto",
          "import": [
            {
              "name": "alexa-layouts",
              "version": "1.7.0"
            }
          ],
          "resources": [],
          "styles": {},
          "layouts": {},
          "mainTemplate": {
            "parameters": [
              "payload"
            ],
            "items": [
              {
                "type": "Container",
                "width": "100vw",
                "height": "100vh",
                "items": [
                  {
                    "type": "Text",
                    "text": "${payload.myDocumentData.title}"
                  }
                ]
              }
            ]
          }
        },
        "datasources": {
          "myDocumentData": {
            "title": "This is a very simple sample"
          }
        }
      }
    ]
  }
}

Object type data sources

The simple data source shown previously is an example of an untyped data source that defines a set of properties. APL also supports typed data sources, which follow a defined structure. This allows additional functionality, such as using transformers to manipulate the data.

The only supported data source type is object. A typed data source has the following properties:

Property Type Required Description
type object Yes Must be "object".
properties object No An object containing bindable properties that can be used with transformers.
objectID String No An optional identifier for an object data source.
description String No Optional description of the data source.
transformers Array No An array of transformers that are applied to values in the properties object.

This example shows an object data source with a textToSpeech transformer. The transformer references data within the properties object. Refer to Transformers, later, for more about how to use transformers.

{
  "myDocumentData": {
    "type": "object",
    "properties": {
      "title": "This is another very simple sample.",
      "mainText": "Note these properties are in a <code>properties</code> object."
    },
    "transformers": [
      {
        "inputPath": "title",
        "outputName": "titleSpeech",
        "transformer": "textToSpeech"
      }
    ]
  }
}
Was this page helpful?

Last updated: Nov 28, 2023