APL Import

An Alexa Presentation Language (APL) import lets you import an APL Package. You can use the resources, styles, layouts, and other items defined in the imported package within your document. You define the imports in the import property of an APL document.

Package imports form a directed dependency graph. Resource, style, and layout lookup is depth-first, following the package import order. For example, assume document A depends on packages B and C, and packages B and C depend on the package D. The search order for the definition of a resource is therefore A, B, C, and then D. This means that document A can override any of the resources, styles, or layouts defined in B, C, or D.

All import properties support data binding. Data-binding expressions within import properties can access the properties available in the initial data-binding context (see Initial data-binding context.

Common properties

All import types in APL 2023.3 or later have the common properties shown in the following table.

Property Type Required Description

loadAfter

Array

No

The list of the import names this import should load after.

type

String

No

Import type. The default is package.

when

Boolean

No

When false, ignore this import.

loadAfter

Identifies a set of imports after which this import loads in the same import block. Follows same pattern as name.

Any cyclic dependencies cause the document processing to fail.

type

Type of the import. An APL import can be one of the types shown in the following table.

Type Description

allOf

Process an array of imports

oneOf

Process single import, similar to the way the Select Command works.

package

Import single APL Package

when

When true, include the package. When false, ignore this package.

The following example shows using when to override the default style with a custom one depending on the environment.

"import": [
  {
    "when": "${environment.overrideName && environment.overrideVersion}",
    "name": "${environment.overrideName + viewport.mode}",
    "version": "${environment.overrideVersion}",
    "loadAfter": "default-styles"
  },
  {
    "name": "default-styles",
    "version": "1.0"
  }
]

allOf

This type of import includes all the imports in the items array.

An import with the allOf type has the following additional properties, in addition to the Common properties.

Property Type Required Description

items

Array

Yes

Array of imports to include.

The following example uses an allOf import to import two packages: "styles" and "overrides."

{
  "import": [
    {
      "type": "allOf",
      "items": [
        {
          "name": "styles",
          "version": "1.0"
        },
        {
          "name": "overrides",
          "version": "1.0",
          "loadAfter": [
            "styles"
          ]
        }
      ]
    }
  ]
}

You can also use the when property to conditionally include multiple packages. The following example imports both the hub-styles and hub-overrides packages when the viewport.mode for the device is hub.

{
  "import": [
    {
      "type": "allOf",
      "when": "${viewport.mode == 'hub'}",
      "items": [
        {
          "name": "hub-styles",
          "version": "1.0"
        },
        {
          "name": "hub-overrides",
          "version": "1.0",
          "loadAfter": [
            "hub-styles"
          ]
        }
      ]
    }
  ]
}

items

Array of imports to include.

oneOf

Select a single import from the items array. The document imports the first item where when evaluates to true.

An import with the oneOf type has the following additional properties, in addition to the Common properties.

Property Type Required Description

items

Array

Yes

An ordered array of imports to select from.

name

String

No

The name of the import.

otherwise

Array

No

Array of imports to process if none were selected from items array.

version

String

No

The version of the import.

In the following example, the document imports one of three different possible styles packages, depending on the value of viewport.mode.

{
  "import": [
    {
      "type": "oneOf",
      "items": [
        {
          "when": "${viewport.mode == 'hub'}",
          "name": "styles",
          "version": "1.0",
          "source": "https://styles.com/hub.json"
        },
        {
          "when": "${viewport.mode == 'tv'}",
          "name": "styles",
          "version": "1.0",
          "source": "https://styles.com/tv.json"
        },
        {
          "name": "styles",
          "version": "1.0",
          "source": "https://styles.com/generic.json"
        }
      ]
    }
  ]
}

You can include multiple oneOf types and combine them with other types and even use them in hierarchy.

{
  "import": [
    {
      "type": "oneOf",
      "name": "styles",
      "items": [
        {
          "when": "${viewport.mode == 'hub'}",
          "type": "oneOf",
          "version": "1.0",
          "items": [
            {
              "when": "${viewport.width > viewport.height}",
              "source": "https://styles.com/hub-landscape.json"
            },
            {
              "source": "https://styles.com/hub-portrait.json"
            }
          ]
        },
        {
          "when": "${viewport.mode == 'tv'}",
          "version": "1.0",
          "source": "https://styles.com/tv.json"
        }
      ],
      "otherwise": [
        {
          "source": "https://styles.com/generic.json"
        }
      ]
    },
    {
      "name": "overrides",
      "version": "1.0",
      "dependsOn": [
        "styles"
      ]
    }
  ]
}

items

Array of imports to select from when processing a oneOf import type.

name

When specified, the name is applied to every import in items and otherwise fields. The name property then becomes optional for the child package type. Follows the same pattern as name.

The following example shows an oneOf import with the name override. The document selects one of the provided packages based on the environment conditions and names that import "override".

{
  "import": [
    {
      "type": "oneOf",
      "name": "override",
      "version": "1.2",
      "items": [
        {
          "when": "${environment.needToOverride}",
          "source": "https://URL1"
        },
        {
          "type": "package",
          "version": "1.3",
          "source": "https://URL2"
        }
      ]
    }
  ]
}

otherwise

The otherwise imports are processed if none of the imports in the items array were selected.

version

When specified, the version is applied to every import in items and otherwise fields. The version property then becomes optional for the child package type. Follows the same pattern as version.

package

Specifies the package to import. An import with the package type is equivalent to an import in versions of APL before 2023.3.

An import with the package type has the following additional properties, in addition to the Common properties.

Property Type Required Description

name

String

Yes

The name of the import.

source

URL

No

When provided, a URL from which to download the package.

version

String

Yes

The version of the import.

Packages use one of two mechanisms to download.

  • When you provide the source property, the document downloads the package from the specified source URL.
  • When you don't provide the source property, the document retrieves the package from an Alexa-supported central repository of packages, using the package name and version properties. For the current set of Amazon-provided packages, see Alexa Design System for APL.

The resources, styles, and layouts defined in packages are accessible from the current package.

The device runtime software caches packages. The device considers that two packages are identical if their name and version properties match, even if they have specified different source properties. The time to live (TTL) of a package is determined by the TTL received during download.

As you develop and test a package, assign it a unique pre-release or build tag each time you modify the package. This forces the runtime to reload the new version of the package rather than using the cached version during testing.

When you host your own APL packages on a site such as Amazon S3, be sure to enable Cross-Origin Resource Sharing for any APL resources hosted on an HTTPS endpoint. For more about creating and hosting your own package, see Host Layouts, Graphics, and Other Resources in an APL Package.

name

Package names follow the pattern [a-zA-Z][a-zA-Z0-9-]*.

source

The source property, if specified, provides the URL location from which to download the package. When not specified, the package is retrieved from an Alexa-supported central repository. For the current set of Amazon-provided packages, see Alexa Design System for APL.

Use https instead of http for package source URLs. Many Alexa devices don't support the http scheme in skill APL documents for security reasons.

version

Package versions should follow the semantic versioning convention given by the following grammar:

vers         ::= <<release>> <<prerelease>>? <<build>>?
release      ::= <<number>> "." <<number>> "." <<number>>
prerelease   ::= "-" <<identifier>> ( "." <<identifier>> )*
build        ::= "+" <<identifier>> ( "." <<identifier>> )*
identifier   ::= [a-zA-Z0-9-]+
number       ::= [0-9] | [1-9][0-9]+

Examples of valid package versions include: 10.2.1, 0.1.10-beta.3, and 0.9.7-alpha2.17+build.1002.

Was this page helpful?

Last updated: Nov 28, 2023