Ti ringraziamo per la visita. Questa pagina è per il momento disponibile solo in inglese.

APL Data Sources and Transformers

(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 ${..} style APL 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.0",
          "theme": "auto",
          "import": [
            {
              "name": "alexa-layouts",
              "version": "1.0.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.

A typed data source has the following properties:

xpressions to speech for use with the [SpeakItem command]. See Transformers.

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 an ssmlToSpeech transformer. The transformer references data within the properties object. Refer to Transformers, later, for more about how these are used.

{
  "myDocumentData": {
    "type": "object",
    "properties": {
      "title": "This is a very simple sample"
    },
    "transformers": [
      {
        "inputPath": "title",
        "outputName": "titleSpeech",
        "transformer": "ssmlToSpeech"
      }
    ]
  }
}

Transformers

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

  • ssmlToSpeech: Converts plain text or Speech Synthesis Markup Language (SSML) into speech appropriate for binding with 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.

  • ssmlToText: A transformer that converts SSML to plain text.

  • textToHint: A transformer that adds the Alexa wake word (Alexa, Computer, Echo or Amazon) to convert text in to an Alexa hint string.

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 part to be translated
outputName String No Name of the property to be added to the object. If no outputName is supplied, the inputPath will be overwritten with the transformed output.

The inputPath may unambiguously reference a single entity in the source object, or may reference a set of entities using wildcard properties or unresolved arrays. Each property that matches the inputPath will be 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": [],
        "outputName": [],
        "transformer": "ssmlToSpeech"
      }
    ]
  }
}
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

The following do not work:

  • family[3].name – Does not work - See rule #1

  • family[1].names – Does not work - See rule #1

  • family[0] { "name": "Alex", "relation": "wife" } Does not work - see rule #3

ssmlToSpeech Transformer

The SSML to speech transformer converts an SSML string into a speakable entity. The SSML to speech transformer has the properties shown in this table:

Property Type Required Description
transformer ssmlToSpeech Yes The name of the transformer
inputPath String Yes Path within the object to the part to be transformed
outputName String Yes Name of the property to be added to the object

The output from the SSML to speech transformer should be attached 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.

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

Next, the code below shows the corresponding object data source and transformers you should send as part of your skill request.

{
  "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 must use 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. It has the same properties as the ssmlToSpeech transformer except the transformer value must be set to ssmlToText.

textToHint Transformer

Skill developers can use the textToHint transformer to automatically add the correct wake word to a hint string shown in an APL document instead of guessing the device wake word or defaulting to "Alexa". The textToHint transformer is applied to a property on a data source of type object that binds to the AlexaFooter layout. This table shows the properties applicable to a textToHint transformer.

Property Type Required Description
transformer textToHint Yes This property must be set to textToHint to invoke the text to hint transformer.
inputPath string Yes The path of the data source value that needs to be transformed.
outputName string No The name of the data source property where the transformed output will be stored. This output property will always be a sibling of the input property. If an outputName isn't provided the value in the inputPath will be replaced with the output of the transformer.

To present a hint, import the alexa-layouts package into the APL document and then use the AlexaFooter layout that is part of the package in the APL document. The following code sample shows an APL document that uses an AlexaFooter layout to present the hint. Note how AlexaFooter's footerHint property is bound to a property of the catFactData data source.

{
    "type": "APL",
    "version": "1.0",
    "import": [{
        "name": "alexa-layouts",
        "version": "1.0.0"
    }],
    "mainTemplate": {
        "parameters": [
            "payload"
        ],
        "items": [
            {
                "type": "Container",
                "items": [
                    {
                        "type": "AlexaHeader",
                        "title": "${payload.catFactData.properties.title}",
                        "attributionImage": "${payload.catFactData.properties.logoUrl}"
                    }
                ]
            },
            {
                "type": "ScrollView",
                "item": {
                    "type": "Text",
                    "id": "catFactText",
                    "text": "${payload.catFactData.properties.catFact}"
                }
            },
        {
            "type": "AlexaFooter",
            "footerHint": "${payload.catFactData.properties.hintString}"
        }
      ]    
    }
 }

The following code illustrates how skill developers can bind data sources to the footerHint to their AlexaFooter. Using catFactData as an example, the catFactData data source contains a textToHint transformer which is applied to the hintString property of the data source. Note that in order to use the transformer, the properties to be transformed must be placed in a properties object inside the object data source. This transformer will transform hintString into a Try "Alexa,… -style hint that can be presented to the end user.

{
    "datasources": {
        "catFactData": {
            "type": "object",
            "properties": {
                "title": "Cat Fact #9",
                "logoUrl": "https://.../logo.png",
                "catFact": "Not all cats like catnip.",
                "hintString": "show me a persian cat fact"
            },
            "transformers": [
                {
                  "inputPath": "hintString",
                  "transformer": "textToHint"
                }
            ]
        }
    }
 }