Transformers (APL 1.0)

Note: Learn how to improve your skills with APL with Build visually rich experiences using APL at the Alexa Learning Lab.

(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)

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"
                }
            ]
        }
    }
 }

Was this page helpful?

Provide feedback

Last updated: Nov 28, 2023