General structure of APL documents

An APL document is a JSON structure. It defines a template to display content on the viewport (the region that the user can view on a multimodal device). The document controls the overall structure and layout of the visual response. The following list shows a few additional terms that you should become familiar with:

  • An APL component is a primitive UI element that displays on the viewport, such as a simple text box. Components are the basic building blocks you use to construct an APL document.
  • A layout combines components into a reusable template and gives it a name. You can place the layout in your document by referencing its name. Referencing a layout makes the document easier for you to maintain as you change your design.
  • An APL package bundles together all of the previously mentioned elements so that you can use them across multiple APL documents. You can import packages into your document.

For more details on APL fundamentals, see Understand Alexa Presentation Language (APL).

At a minimum, most APL documents define the following elements:

  • Type (required): "APL"
  • APL version (required): for example: "1.7"
  • Theme: for example, "dark"
  • Imports of additional packages
  • Components of the mainTemplate (the main responsive template of an APL document)

The following JSON shows how these elements look in an APL document.

    "type": "APL",
    "version": "1.7",
    "theme": "dark",
    "import": [],
    "mainTemplate": {
        "items": []

Note that items in the mainTemplate are APL components and layouts.