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

An APL document is a JSON object that defines a template to display on a device with a screen. The APL document controls the structure and layout. You send the document to the device with the Alexa.Presentation.APL.RenderDocument directive.

Sample APL documents

Here is a simple APL document that inflates a single Text component.

{
  "type": "APL",
  "version": "1.0",
  "mainTemplate": {
    "item": {
      "type": "Text",
      "text": "Hello, world"
    }
  }
}

A richer APL document can include imported packages, resource definitions, style definitions, data sources, and custom layouts.

{
  "type": "APL",
  "version": "1.0",
  "description": "This is a sample use of BodyTemplate3",
  "import": [
    {
      "name": "sample-import",
      "source": "https://example.com/packages/fictitious-package-import-example",
      "version": "1.0"
    },
    {
      "name": "alexa-layouts",
      "version": "1.0.0"
    }
  ],
  "resources": [
    {
      "colors": {
        "myBlue": "#0022f3"
      }
    }
  ],
  "styles": {
    "textBlockStyle": {
      "fontSize": 24,
      "color": "@myBlue"
    }
  },
  "layouts": {
    "myBody": {
      "parameters": [
        "block1",
        "block2"
      ],
      "item": {
        "type": "Container",
        "direction": "column",
        "items": [
          {
            "type": "Text",
            "text": "${block1}",
            "style": "textBlockStyle"
          },
          {
            "type": "Text",
            "text": "${block2}",
            "style": "textBlockStyle"
          }
        ]
      }
    }
  },
  "mainTemplate": {
    "parameters": [
      "payload"
    ],
    "item": {
      "type": "BodyTemplate3",
      "title": "${payload.myTitle}",
      "scrollItem": {
        "type": "myBody",
        "block1": "${payload.myTextBlock1}",
        "block2": "${payload.myTextBlock2}"
      }
    }
  }
}

Document properties

The properties in the top-level APL document object are:

Property	Type	Required	Description
description	String	No	An optional description of this document.
import	Array of IMPORTS	No	A list of references to external APL packages.
layouts	Map of LAYOUT	No	Custom complex components. See Layout.
mainTemplate	LAYOUT	Yes, in top-level documents	The starting Layout.
resources	RESOURCES	No	Resource definitions. See Resources.
styles	Map of STYLES	No	A map of style definitions. See Styles.
type	String	Yes	Must be "APL".
version	String	Yes	Version string of the APL specification. Currently "1.0".

The mainTemplate property is required in a top-level APL document. This defines the layout that will be inflated and displayed first on the screen. The mainTemplate property is only used by the top-level APL document. A mainTemplate appearing in an imported package is ignored.

import

The import property defines a list of named APL packages that are required to inflate the templates and/or resources from this document. The imported packages are specified in a list of package references, where each entry in the list has the following properties:

Property	Type	Required	Description
name	String	Yes	The name of the Package to import
version	String	Yes	The version of the Package to import.
source	URL	No	If provided, a URL to download the package from.

Here is an example that uses the alexa-layouts package, and an external package.

  "import": [
    {
      "name": "alexa-layouts",
      "version": "1.0.0"
    },
    {
      "name": "my-own-package",
      "source": "https://www.example.com/my-custom-package.json"
    }	
  ]

An APL package is a JSON file that may be hosted on another site, such as Amazon S3. Ensure that Cross-Origin Resource Sharing is supported for any APL resources hosted on an HTTPS endpoint.

Package imports form a directed dependency graph. Resource, style, and layout lookup is depth-first, following the package import order. For example, if document A depends on packages B and C, and documents B and C depend on the package D, then the search order for the definition of a resource will be A, B, C, and then D. Thus, package A can override any of the resources, styles, or layouts defined in B, C, or D. Dependency loops are forbidden.

Packages may be downloaded by one of two mechanisms. If the source property is specified, the package will be downloaded from that location. If the source property is not specified, the package will be retrieved from an Alexa-supported central repository of packages, using the package name and version properties. Packages will be cached by the device runtime software. Two packages are considered to be identical if their name and version properties match (even if they have specified different source properties). The time to live (TTL) of a package will be determined by the TTL received during download. It is recommended that packages under active development be assigned a unique prerelease or build tag each time the package is modified to ensure that the runtime will correctly reload the package.

layouts

The layouts property is a map of layout name to layout definition. See APL Layout.

mainTemplate

The mainTemplate property is a defined layout. This is the layout that will be inflated when the document is first instantiated on the screen.

The parameters defined in the mainTemplate will be bound to data sources provided in the directive that inflated the document.

The mainTemplate is the layout that will be inflated when the document is first shown on the screen. The parameters defined in the mainTemplate will be bound to data sources provided by the RenderDocument directive that initiated the display of the APL document. See RenderDocument.

resources

The resources property is an array of resource blocks.

styles

The styles property is an object mapping style name to style definition.

Inflation of An APL document

The APL document is inflated into an on-screen display, using the following steps:

1. Put the list of import packages on the package processing queue.

2. For each package on the queue:

Add the package to the directed graph of package dependencies
Check if the package is available either in the (a) on-device cache, or (b) the packages portion of the directive. If the package is not on-device, use the source value of the import list to download the package from the named URL.
Add the packages import list to the package processing queue

3. Construct an initial data-binding context with a viewport property.

4. Construct an initial set of named resources using the built-in resources for the device.

5. Traversing the directed graph of package dependencies in depth-first order, for each package:

For each resource block in the resources array:

Evaluate the when clause in the current data-binding context. If the when clause evaluates to false, skip this block. Otherwise, if the when clause evaluates to true:

Evaluate each boolean in the boolean map and add to the resources
Evaluate each color in the colors map and add to the resources
Evaluate each number in the numbers map and add to the resources
Evaluate each string in the strings map and add to the resources
Evaluate each dimension in the dimensions map and add to the resources

6. For each parameter in the mainTemplate:

Identify a data source with the same name
Update the data-binding context to set that name to the value in the data source.

7. Inflate the mainTemplate following standard layout inflation logic.

Was this page helpful?

Provide feedback

Last updated: Feb 29, 2024