Data Sources (APL for Audio)

A data source is a JSON structure that defines data you can bind to an APL document. When you send an APL document to Alexa with the Alexa.Presentation.APLA.RenderDocument directive, you can include one or more data sources. You bind the data sources by including them in the parameters of the APL document. You can then use a data-binding expression to bind the data to component properties within the document.

Send a data source in the RenderDocument directive

For APL for Audio, pass the data source to Alexa in the datasources object as part of the Alexa.Presentation.APLA.RenderDocument directive. This datasources object contains an object representing each data source.

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.APLA.RenderDocument",
        "token": "developer-provided-string",
        "document": {
          "type": "APLA",
          "version": "0.91",
          "mainTemplate": {
            "parameters": [
              "payload"
            ],
            "item": {}
          }
        },
        "datasources": {
          "myDocumentData": {
            "text": "This is a simple sample.",
            "user": {
              "name": "John"
            }
          }
        }
      }
    ]
  }
}

Bind the data source to the document

Use data-binding expressions to bind data in the data source to component properties in your APL document.

To bind data in a data source to component properties in your document

  1. Declare a parameter in the mainTemplate.parameters array called payload. This binds the entire datasources object to the "payload" parameter.
  2. In the component properties, refer to the data source properties with the syntax ${payload.dataSourceName.propertyName}.

For example, assume you have the following datasources object with two data sources:

{
  "myDocumentData": {
    "text": "This is a simple sample",
    "user": {
        "name": "John"
    }
  },
  "myDocumentData2": {
    "property": "This is a second data source within datasources"
  }
}

In this example, the data-binding expression to access the value of the "name" property is ${payload.myDocumentData.user.name}.

Was this page helpful?

Last updated: Nov 28, 2023