APL Data Sources

A data source is a JSON structure that defines data you can bind to an Alexa Presentation Language (APL) document. When you send an APL document to Alexa with the 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

Pass a data source to Alexa in an optional datasources object. The datasources object is part of the RenderDocument directive, but outside of the APL document. The datasources object contains an object representing each data source.

The following example shows a skill response with the RenderDocument directive. It passes the document and a data source named myDocumentData. The example omits the full document content 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": {
          "type": "APL",
          "version": "2024.3",
          "mainTemplate": {
            "parameters": [
              "myDocumentData"
            ],
            "items": []
          }
        },
        "datasources": {
          "myDocumentData": {
            "title": "Example of a title field in a basic data source"
          }
        }
      }
    ]
  }
}

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 that matches the key for the data source object.
2. In the component properties, refer to the data source properties with the syntax ${dataSourceName.propertyName} where dataSourceName is the same key you used in mainTemplate.parameters.

For example, assume you have the following data source object.

{
  "myDocumentData": {
    "title": "Example of a title field in a basic data source."
  }
}

The key for this data source is myDocumentData. Declare the parameter myDocumentData in mainTemplate.parameters.

{
  "type": "APL",
  "version": "2024.3",
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": []
  }
}

Then, use a data-binding expression to bind a component property to the data in myDocumentData. Use the myDocumentData key to access the properties. For example, the expression ${myDocumentData.title} resolves to the value "Example of a title field in a basic data source."

The following example shows an APL document that displays the content from the myDocumentData.title property in a text component.

{
  "type": "APL",
  "version": "2024.3",
  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.7.0"
    }
  ],
  "mainTemplate": {
    "parameters": [
      "myDocumentData"
    ],
    "items": [
      {
        "type": "Container",
        "width": "100vw",
        "height": "100vh",
        "items": [
          {
            "type": "Text",
            "text": "${myDocumentData.title}"
          }
        ]
      }
    ]
  }
}

Data source types

APL supports data sources with types and free-form data sources without types.

• Free-form ("untyped") – A JSON object with an arbitrary set of properties you define. The myDocumentData example shown earlier is an example of a free-form data source.
• Typed – A JSON object with a structure defined by the Alexa Skills Kit. You must use typed data sources for some functionality. APL supports two typed data sources
  • object – Required to use transformers to manipulate the data, such as converting SSML text to speech or creating a hint that includes the configured wake word for a device.
  • dynamicIndexList – Required to use lazy loading to load data progressively as the user scrolls and for modifying the data source after rendering the document.
  • dynamicTokenList – Required to use token-based lazy loading to load data a page at a time.

object data source

The object data source type adds properties required for transformers. You use transformers to manipulate the data. For example, you use a transformer to put wake word configured for the user's device into a hint string.

The object data source has the following properties:

An object data source can also include other arbitrary properties that you can bind to your document as needed.

The following example shows an object data source with data in both the properties object and an arbitrary property (hello). The data source also has the textToSpeech transformer. The transformer references data within the properties object. For more about how to use transformers, see Transformers.

{
  "myDocumentData": {
    "type": "object",
    "properties": {
      "title": "This is another very simple sample.",
      "mainText": "Note these properties are in a <code>properties</code> object."
    },
    "hello": "Hello, World!"
    "transformers": [
      {
        "inputPath": "title",
        "outputName": "titleSpeech",
        "transformer": "textToSpeech"
      }
    ]
  }
}

Dynamic data sources

APL supports two types of dynamic data sources. Use dynamic data sources to update the data source after sending it to Alexa and therefore change the values on the screen without sending an entirely new document. These data sources also enable lazy loading, where Alexa displays large lists progressively as the user scrolls through the content.

There are two types of dynamic data sources:

• dynamicIndexList – Uses an index to keep track of the items. Users can scroll to arbitrary locations in the list.
• dynamicTokenList – Uses tokens to keep track of the items. Users can scroll forward or backwards one page at time.

dynamicIndexList data source

The dynamicIndexList data source adds properties required for lazy loading and dynamic data sources.

The dynamicIndexList data source has the properties shown in the following table.

The following example shows a dynamicIndexList data source that initially displays ten items. Alexa asks for more items to load when the user scrolls forward until all 200 items have loaded.

{
  "dynamicSourceExample": {
    "type": "dynamicIndexList",
    "listId": "my-list-id",
    "startIndex": 0,
    "minimumInclusiveIndex": 0,
    "maximumExclusiveIndex": 200,
    "items": [
      {"primaryText":"item 1"},
      {"primaryText":"item 2"},
      {"primaryText":"item 3"},
      {"primaryText":"item 4"},
      {"primaryText":"item 5"},
      {"primaryText":"item 6"},
      {"primaryText":"item 7"},
      {"primaryText":"item 8"},
      {"primaryText":"item 9"},
      {"primaryText":"item 10"}      
    ]
  }
}

dynamicTokenList data source

The dynamicTokenList data source has the properties shown in the following table.

Bind a dynamic data source to your APL document

To use a dynamic data source in your document, you must use the data source key in the mainTemplate.parameter. Don't use the pre-1.3 "payload" parameter.

Then, use the data source key in your data-binding expression. For example, assume you create a data source called dynamicSourceExample. To bind to this data source, use the expression ${dynamicSourceExample}. This syntax provides your document with the set of items in the items property. Don't include the items property in the expression.

Bind the data source to the data property of a Pager, GridSequence, Sequence, or Container. Note that Container doesn't support lazy loading, but it does support dynamic data sources. You can't use a dynamicIndexList with any other component types.

This example shows a Sequence that displays the ten items defined in a data source called dynamicSourceExample data source.

{
  "type": "APL",
  "version": "2024.3",
  "mainTemplate": {
    "parameters": [
      "dynamicSourceExample"
    ],
    "items": [
      {
        "type": "Sequence",
        "data": "${dynamicSourceExample}",
        "items": {
          "type": "Text",
          "text": "${data.primaryText}"
        }
      }
    ]
  }
}

Use directives and requests to manage the list

The Alexa.Presentation.APL interface provides several directives and requests for managing a dynamic data source.

With a dynamicIndexList data source, you can load items progressively. You can also change the contents of the list. With a dynamicTokenList, you can load additional pages of content as the user scrolls the list.

To load items progressively with a dynamicIndexList

1. Send the dynamicIndexList data source with your initial set of items in the RenderDocument directive.
2. As the user scrolls the list, Alexa sends your skill LoadIndexListData requests to ask for more items to display.
3. Respond to the LoadIndexListData request with the SendIndexListData directive with another dynamicIndexList data source containing the next set of items to display.

To change the contents of a dynamicIndexList

1. Send the initial dynamicIndexList data source with a set of list items in the RenderDocument directive.
2. Use the UpdateIndexListData directive to make updates to the data, such as inserting new items or deleting existing items.

To load pages of data with a dynamicTokenList

1. Send the dynamicTokenList data source with your initial set of items in the RenderDocument directive.
2. As the user scrolls the list, Alexa sends your skill LoadTokenListData requests to ask for more items to display.
3. Respond to the LoadTokenListData request with the SendTokenListData directive with another dynamicTokenList data source containing the next set of items to display.

For more about requests and directives, see the Alexa.Presentation.APL Interface Reference.

Sequence component size and the number of items to load

When you use a dynamic data source with a Sequence for lazy loading, send enough items to fill the Sequence at least three times in each response. For example, if the Sequence is tall enough to display five items, your initial dynamicIndexList should contain at least 15 items. Each subsequent SendIndexListData or SendTokenListData directive should also contain at least 15 items. The same applies for a horizontally-scrolling Sequence. If the Sequence is wide enough to display five items, send at least 15 in each call.

Providing a large enough set of items improves the list performance and user experience. If you send a small number of items in each response, the user experience might be poor as Alexa must then continually request new items as the user scrolls.

To make sure that the Sequence height or width remains static when loading items and scrolling, don't use the auto setting for the height or width properties on the Sequence. Set the Sequence size to either a relative or absolute dimension.

Related topics

• Transformers
• Alexa.Presentation.APL Interface Reference
• Data-binding Syntax

Last updated: Nov 28, 2023