# IR Module

## The IR abstraction layer

In order to build an Alexa Conversations skill, a developer needs to provide a set of artifacts such as dialog samples, actions, types, annotated utterance sets, catalogs, and more. Different tools may be used to generate these artifacts. We are offering the Alexa Conversations Description Language (ACDL) as a Domain-Specific Language (DSL) for declaring these artifacts for ALexa Conversations. We are also working on the evolution of the Web-based guided experience.

After a developer has described their skill's artifacts, they need to be packaged and given to the Alexa cloud to kick off the Alexa Conversations simulation and machine learning processes that will train and deploy the dialog policy model. The code for the actions will also be deployed.

We need an abstraction layer to act as the interface/contract between the developer-facing tools such as the ACDL compiler and the Alexa Conversations infrastructure. This way, different tools built on top of the shared layer can interoperate. We can also build reusable validation, creation, loading processing logic for the abstraction layer.

We call this abstraction layer "Intermediate Representation" (IR). The IR for an Alexa Conversations skill consists of 1-N files that we call **modules**.

## IR Module structure

In order to build an Alexa Conversations skill, the developer has to provide a set of artifacts such as dialog samples, action interfaces, catalogs, annotated utterance sets, prompts, presentation files, the code for the implementation of the actions, and more. With the exception of code and presentation files, all the other artifacts are compiled to **modules** . A module is a JSON file that adheres to the "Intermediate Representation" (IR) format. An IR module can represent artifacts necessary to drive the Alexa Conversations simulation and machine learning flows (see [About Alexa Conversations](https://developer.amazon.com/en-US/docs/alexa/conversations/about-alexa-conversations.html) for a high-level description).

The ASK CLI tooling generates IR modules and pushes them to the cloud, together with any code that should be deployed.

The following is an example of an empty IR module file.

```json
{
  "schema": "https://amazonalexa.com/ask/2020/12/Module",
  "expressions": []
}
```

## Expressions

An IR Module is structured as a set of expressions. This specification defines the small set of expressions. The following is an example of a set of expressions representing the declaration of the `Person` type.

```json
{
  "schema": "https://amazonalexa.com/ask/2020/12/Module",
  "expressions": [
    {
      "kind": "QualifiedNameDeclaration",
      "name": "foo.bar.Person",
      "expression": {
        "kind": "TypeDeclaration",
        "properties": {
          "firstName": {
            "type": {
              "kind": "TypeReference",
              "type": "com.amazon.alexa.schema.String"
            },
            "optional": false
          },

          "lastName": {
            "type": {
              "kind": "TypeReference",
              "type": "com.amazon.alexa.schema.String"
            },
            "optional": false
          },

          "dateOfBirth": {
            "type": {
              "kind": "TypeReference",
              "type": "com.amazon.alexa.schema.Number"
            },
            "optional": false
          }
        }
      }
    }
  ]
}
```

In the above example, the `TypeDeclaration` expression represents the declaration of a type with some properties. The `QualifiedNameDeclaration` expression represents the declaration of the name `foo.bar.Person` for the `TypeDeclaration` expression.

The container of the set of expressions is a [Module](schemas/module.md).

[Index of all schemas](schemas/README.md)

## Structural vs Semantic validation

The set of JSON Schemas that are part of this specification define the document structure of IR modules. For an IR module file to be valid, it has to adhere to the [Module](schemas/module.md) JSON Schema. There are [semantic validation rules](semantic-rules.md) that cannot be expressed in JSON Schema. These rules must be considered when reading or writing IR modules.