# LAST Specification - Relottie API
Learn about the Lottie Abstract Syntax Tree (LAST) specification used by Relottie to represent Lottie animations. Essential for plugin development.

# API Reference: `@lottiefiles/last` (LAST Specification)

This page details the **`@lottiefiles/last`** package, which defines the **L**ottie **A**bstract **S**yntax **T**ree (LAST) specification. LAST is the tree structure used by relottie to represent Lottie JSON animations programmatically.

Understanding LAST is crucial for writing plugins that analyze or transform Lottie files.

## Installation

While `@lottiefiles/relottie` includes core functionality, you might install `@lottiefiles/last` directly if you need access to the type definitions for plugin development or other advanced use cases:

```bash
npm install @lottiefiles/last
# or
yarn add @lottiefiles/last
```

## Core Concepts

- **AST for Lottie:** LAST provides a standard way to represent the nested structure and properties of Lottie JSON as a tree.
- **Based on `unist`:** LAST extends the [`unist`](https://github.com/syntax-tree/unist) (Universal Syntax Tree) specification. This means it inherits the basic node structure (`type`, `children`, `value`, `position`) and is compatible with the rich ecosystem of `unist` utilities for tree manipulation and traversal (like [`unist-util-visit`](https://github.com/syntax-tree/unist-util-visit)).
- **Semantic Titles:** A key feature of LAST is the `title` property on parent nodes, which provides the Lottie-specific semantic meaning (e.g., `version`, `layer-image`, `transform-opacity`) based on the [Lottie documentation](https://lottiefiles.github.io/lottie-docs/), distinguishing nodes beyond their basic JSON key.
- **TypeScript Types:** The package exports TypeScript interfaces for all defined node types, enabling type safety in your plugins.

## Node Types

The following are the core node types defined by the LAST specification (based on the source documentation). See the package source code or generated TypeDocs for the complete set of `title` values.

### Abstract Interfaces (from `unist`)

- **`Parent`**: Base interface for nodes containing other nodes (`children`). In LAST, it also includes the semantic `title` property.
  ```typescript
  interface Parent extends UnistParent {
    title: AnyTitle; // Lottie's qualified semantic name
    // children: Node[];
    // position?: Position;
  }
  ```
- **`Literal`**: Base interface for nodes containing a literal `value`.
  ```typescript
  interface Literal extends UnistLiteral {
    // value: any;
    // position?: Position;
  }
  ```

### Core LAST Nodes

- **`Root`**: Represents the entire Lottie animation object. It's the top-level node.

  ```typescript
  interface Root extends Omit<ObjectNode, "type"> {
    type: "root";
    title: "animation";
    hasExpressions: boolean; // Indicates if Lottie uses expressions
  }
  ```

  - The `hasExpressions` flag is important for [Security Considerations](/docs/tools/relottie/ecosystem/security).

- **`Primitive`**: Represents a primitive JSON value.

  ```typescript
  type PrimitiveValueType = "string" | "number" | "boolean" | "null";
  type PrimitiveValue = string | number | boolean | null;

  interface Primitive extends Literal {
    type: "primitive";
    value: PrimitiveValue;
    valueType?: PrimitiveValueType;
  }
  ```

- **`KeyNode`**: Represents the key (property name) in a JSON key-value pair.

  ```typescript
  interface KeyNode extends Literal {
    type: "key";
    value: string;
  }
  ```

- **`Member` (Interface)**: A base interface shared by `Attribute`, `Element`, and `Collection`. Represents a keyed member of an object.

  ```typescript
  interface Member extends Parent {
    key: KeyNode | string; // The JSON key
    title: AttributeTitle | CollectionTitle | ElementTitle; // Semantic Lottie title
    // children: ...
  }
  ```

- **`Attribute`**: A `Member` whose value is a single `Primitive`.

  ```typescript
  interface Attribute extends Member {
    type: "attribute";
    title: AttributeTitle;
    children: [Primitive] | []; // Contains zero or one Primitive
  }
  ```

- **`Element`**: A `Member` whose value is a JSON object, represented by an `ObjectNode`.

  ```typescript
  interface Element extends Member {
    type: "element";
    title: ElementTitle;
    children: [ObjectNode] | []; // Contains zero or one ObjectNode
  }
  ```

- **`Collection`**: A `Member` whose value is a JSON array, represented by an `ArrayNode`.

  ```typescript
  interface Collection extends Member {
    type: "collection";
    title: CollectionTitle;
    children: [ArrayNode] | []; // Contains zero or one ArrayNode
  }
  ```

- **`ObjectNode`**: Represents the value part of an `Element` (a JSON object).

  ```typescript
  type ObjectNodeValue = Attribute | Element | Collection;
  interface ObjectNode extends Parent {
    type: "object";
    title: ObjectTitle;
    children: ObjectNodeValue[]; // Contains object members
  }
  ```

- **`ArrayNode`**: Represents the value part of a `Collection` (a JSON array).
  ```typescript
  type ArrayNodeValue = Primitive | ObjectNode | ArrayNode;
  interface ArrayNode extends Parent {
    type: "array";
    title: ArrayTitle;
    children: ArrayNodeValue[]; // Contains array items
  }
  ```

## Security

As noted in the source documentation, Lottie animations can contain JavaScript [expressions](https://lottiefiles.github.io/lottie-docs/expressions/#expressions). The `Root` node's `hasExpressions` property helps identify if expressions are present. Improper handling or execution of untrusted Lottie files containing expressions can lead to security vulnerabilities like Cross-Site Scripting (XSS). Always be cautious when processing Lottie files from untrusted sources.

## Related

- **[Guide: Working with the LAST AST](/docs/tools/relottie/guides/working-with-last):** Practical examples of using the AST.
- **[`@lottiefiles/last-builder`](/docs/tools/relottie/api/last-builder):** Utilities for programmatically creating LAST nodes.
- **[`unist`](https://github.com/syntax-tree/unist):** The underlying syntax tree specification.