APL Data Sources and Transformers

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": "1.1",
          "theme": "auto",
          "import": [
            {
              "name": "alexa-layouts",
              "version": "1.1.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"
      }
    ]
  }
}

Transformers

Transformers convert data in a data source into alternative representations. The RenderDocument directive supports four transformers:

  • ssmlToSpeech: Converts the input Speech Synthesis Markup Language (SSML) into speech you can bind to the speech property of an APL component. The speech associated with the component can then be spoken using a SpeakItem APL command. The use of the audio tag with the ssmlToSpeech transformer is not supported. The text passed to this transformer must be valid SSML enclosed within <speak> tags.
  • ssmlToText: Converts the input SSML to plain text.
  • textToHint: Converts the input to a hint with the correct user-configured wake word for the device (Try "Alexa, This is the hint"). Users can choose the wake word for their devices, so avoid hard-coding the word "Alexa" in your hint.
  • textToSpeech: Converts the input plain text into speech you can bind to the speech property of an APL component. The speech associated with the component can then be spoken using a SpeakItem APL command.

Transformer properties and conversion rules

A transformer converts data from a named property inside a data source, performs the transformation and writes the data back to a property in the original data source. If the outputName is not supplied, a transformer overwrites the input property. All transformers have the base properties shown in this table:

Property Type Required Description
transformer String Yes The type of the transformer.
inputPath String Yes Path within the object to the content to transform. This must reference a property within the properties object in the data source.
outputName String No Name of the property to be added to the object. If no outputName is supplied, the transformer overwrites the inputPath with the transformed output.

The inputPath points to either a single entity in the data source object, or a set of entities using wildcard properties or unresolved arrays. Each property that matches the inputPath is transformed. The inputPath pattern is a symbol followed by some number of node and/or wildcard references.

The following rules apply:

  • A symbol name or array index must match an existing object property or array index inside the properties block. If the match fails, the transformation is abandoned.

  • The location where the output is stored is found by replacing the last non-wildcard node with the outputName. If there are no non-wildcard nodes, the symbol is replaced by outputName.

  • The last non-wildcard node cannot be a numeric index. If the last non-wildcard node is numeric, the transformation is abandoned.

These examples demonstrate how referencing works. Consider the sample data shown here:

{
  "myDocumentData": {
    "type": "object",
    "properties": {
      "name": "Sam Lee",
      "address": {
        "street": "301 Charles Way",
        "city": "Bedford"
      },
      "family": [
        {
          "name": "Alex",
          "relation": "wife"
        },
        {
          "name": "Patty",
          "relation": "daughter"
        }
      ],
      "contacts": [
        "Robin Barnes",
        "Betty Barnes"
      ]
    },
    "transformers": [
      {
        "inputPath": ["see examples in table below"],
        "outputName": ["see examples in table below"],
        "transformer": "textToSpeech"
      }
    ]
  }
}

This table shows how different values in inputPath and outputName would transform the data shown in the above data source.

inputPath Item to be transformed Result stored at:
name "Sam Lee" outputName
address.street "301 Charles Way" address.outputName
contacts.* ["Robin Barnes", "Betty Barnes"] outputName[0], outputName[1]
family[0].name "Alex" family[0].outputName
family[*].name "Alex", "Patty" family[0].outputName, family[1].outputName
address.* "301 Charles Way", "Bedford" outputName.street, outputName.city
family[3].name   Does not work: the family array does not have a value at index 3
family[1].names   Does not work: the value at family[1] does not have a names property
family[0] { "name": "Alex", "relation": "wife" } Does not work: the last non-wildcard node cannot be a numeric index

ssmlToSpeech transformer

The ssmlToSpeech transformer converts an SSML string into a speakable entity. The text passed to this transformer must be valid SSML enclosed within <speak> tags. For plain text, use the textToSpeech transformer instead.

In your document, bind ssmlToSpeech transformer output to the speech property of a component. The code below shows a version of a "Cat Facts" skill that associates speech with a Text component bound to the cat fact.

Note that the text property points to catFactData.properties.catFact, while the speech component points to catFactData.properties.catFactSpeech.

{
  "type": "Container",
  "item": {
    "type": "Text",
    "id": "catFactText",
    "text": "${payload.catFactData.properties.catFact}",
    "speech": "${payload.catFactData.properties.catFactSpeech}"
  }
}

This example shows the corresponding catFactData data source. Note that the properties object has a property catFactSsml that contains the actual text to use in the component. This property is used as input for both the ssmlToSpeech and ssmlToText transformers:

  • The ssmlToSpeech transformer transforms the value of catFactSsml into speech and places the output in a new property called catFactSpeech. Recall that the catFactSpeech property is bound to the speech property in the Text component shown earlier.
  • The ssmlToText transformer transforms the value of catFactSsml into plain text and places the output in a new property called catFact. Recall that the catFact property is bound to the text property in the Text component shown earlier.
{
  "catFactData": {
    "type": "object",
    "properties": {
      "backgroundImage": "https://.../catfacts.png",
      "title": "Cat Fact #9",
      "logoUrl": "https://.../logo.png",
      "image": "https://.../catfact9.png",
      "catFactSsml": "<speak>Not all cats like <emphasis level='strong'>catnip</emphasis>.</speak>"
    },
    "transformers": [
      {
        "inputPath": "catFactSsml",
        "outputName": "catFactSpeech",
        "transformer": "ssmlToSpeech"
      },
      {
        "inputPath": "catFactSsml",
        "outputName": "catFact",
        "transformer": "ssmlToText"
      }
    ]
  }
}

Finally, to read the cat fact, you send Alexa the Alexa.Presentation.APL.ExecuteCommands directive with the SpeakItem command. The code below shows the Alexa.Presentation.APL.ExecuteCommands directive you can use to read the cat fact. Note that the token supplied in the ExecuteCommands directive is required and must match the token provided by the skill in the RenderDocument directive used to render the APL document.

{
  "type": "Alexa.Presentation.APL.ExecuteCommands",
  "token": "[SkillProvidedToken]",
  "commands": [
    {
      "type": "SpeakItem",
      "componentId": "catFactText",
      "highlightMode": "line",
      "align": "center"
    }
  ]
}

ssmlToText transformer

The SSML to text transformer converts a full SSML text string into text that is more appropriate for human reading by removing the SSML markup.

textToHint transformer

The textToHint transformer converts the input to a hint with the correct user-configured wake word for the device (Try "Alexa, This is the hint"). Users can choose the wake word for their devices, so avoid hard-coding the word "Alexa" in your hint. You typically use this transformer with the AlexaFooter responsive component.

For an example of displaying a hint, see Use the textToHint transformer.

textToSpeech transformer

The textToSpeech transformer converts a plain text string into a speakable entity. The text passed to this transformer must be plain text. For SSML text, use the ssmlToSpeech transformer instead.

This transformer works just like the ssmlToSpeech transformer. You bind the textToSpeech transformer output to the speech property of a component, then use the SpeakItem command to speak the text.

This example data source shows the same catFactData data source shown earlier, but with plain text for the catFactText property. In this case, since the catFactText property is already plain text, there is no need for the ssmlToText transformer.

{
  "catFactData": {
    "type": "object",
    "properties": {
      "backgroundImage": "https://.../catfacts.png",
      "title": "Cat Fact #9",
      "logoUrl": "https://.../logo.png",
      "image": "https://.../catfact9.png",
      "catFactText": "Not all cats like catnip."
    },
    "transformers": [
      {
        "inputPath": "catFactText",
        "outputName": "catFactSpeech",
        "transformer": "textToSpeech"
      }
    ]
  }
}

You can then reference this data source in the Text component like this:

{
  "type": "Container",
  "item": {
    "type": "Text",
    "id": "catFactText",
    "text": "${payload.catFactData.properties.catFactText}",
    "speech": "${payload.catFactData.properties.catFactSpeech}"
  }
}

The text property binds to the un-transformed, plain text catFactText property. The speech property binds to the output of the transformer.

Amazon Alexa
Amazon Appstore
Amazon Web Services
Amazon Dash Replenishment