# dotLottie v1.0 Specification

dotLottie is an open-source file format designed to package one or more Lottie animations (opens new window) along with their associated resources, such as images, into a single, compressed file. A dotLottie file is a ZIP archive compressed using the Deflate method, identified by the .lottie file extension and the MIME type application/zip+dotlottie.

# File Structure

A dotLottie file is structured as a ZIP archive with a specific layout to organize its contents efficiently:

.
├─ manifest.json          # Required: Metadata file describing the package
├─ animations/            # Required: Directory containing Lottie JSON animation files
│  ├─ animation_1.json    # Example animation file
│  └─ animation_2.json    # Another animation file
└─ images/                # Optional: Directory for image assets
   ├─ img_1.webp          # Example image asset
   └─ img_2.png           # Another image asset

manifest.json: A required JSON file at the root that provides metadata and configuration details.
animations/: A required folder containing one or more Lottie JSON animation files.
images/: An optional folder for storing image assets referenced by the animations.
All file paths are relative to the root of the ZIP archive.

# Manifest

The manifest.json file serves as the backbone of the dotLottie format, detailing the animations and metadata for the package.

# Location and Format

Location: Must be placed at the root of the dotLottie file and named manifest.json.
Format: Must be a valid JSON file, adhering to standard JSON syntax.

# Properties

The manifest includes a set of properties to describe the dotLottie package:

Property	Type	Required	Description
`animations`	Array<Animation>	Yes	An array of animation objects, each representing an animation in the file.
`version`	String	Yes	The dotLottie specification version (e.g., "1").
`generator`	String	No	The tool or software used to create the dotLottie file (e.g., "dotLottie Creator v1.0").
`activeAnimationId`	String	No	The `id` of the animation to be loaded or played by default.
`author`	String	No	The creator of the dotLottie package (e.g., "John Smith").
`custom`	Object	No	A flexible object for custom key-value metadata (e.g., licensing info).
`description`	String	No	A short description of the package’s purpose or contents.
`keywords`	String	No	Comma-separated tags for searchability (e.g., "animation, ui, lottie").
`revision`	Number	No	A revision number to track updates to the package (e.g., 2).

# Animation Object

Each animation in the animations array is defined by an object with the following properties:

Property	Type	Required	Description
`id`	String	Yes	A unique identifier matching the animation’s filename (without `.json`).
`autoplay`	Boolean	No	If true, the animation plays automatically upon loading (default: false).
`loop`	Boolean / Number	No	Controls looping: `true` (infinite), a number (specific loops), or `false` (no loop).
`speed`	Number	No	Playback speed multiplier (e.g., 1.0 for normal, 0.5 for half speed).
`direction`	Number (1 / -1)	No	Playback direction: 1 (forward) or -1 (reverse).
`playMode`	String	No	Playback style, such as "normal" or "bounce" (player-dependent).
`hover`	Boolean	No	If true, the animation plays on hover (default: false).
`intermission`	Number	No	Delay in milliseconds between loop cycles (e.g., 1000 for 1 second).
`themeColor`	String	No	A hex color code for the animation’s background (e.g., "#FF0000" for red).

Note: Some dotLottie players may not support all of these playback related controls as it can be controlled via the player API.

# Example

Here’s an example manifest.json file with two animations:

{
  "version": "1",
  "generator": "dotLottie Creator v1.0",
  "author": "Jane Doe",
  "description": "A set of UI animations for a mobile app",
  "keywords": "ui, mobile, animation",
  "revision": 1,
  "activeAnimationId": "animation_1",
  "animations": [
    {
      "id": "animation_1",
      "autoplay": true,
      "loop": true,
      "speed": 1.0,
      "direction": 1,
      "playMode": "normal",
      "themeColor": "#FFFFFF"
    },
    {
      "id": "animation_2",
      "loop": 2,
      "speed": 1.5,
      "direction": -1,
      "playMode": "bounce",
      "hover": true,
      "intermission": 1000
    }
  ],
  "custom": {
    "project": "Mobile App UI",
    "license": "CC-BY-4.0"
  }
}

# JSON Schema

The following JSON schema validates the structure of manifest.json:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "manifest.json",
  "type": "object",
  "properties": {
    "version": { "type": "string" },
    "generator": { "type": "string" },
    "activeAnimationId": { "type": "string" },
    "animations": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "autoplay": { "type": "boolean" },
          "loop": { "oneOf": [{ "type": "boolean" }, { "type": "number" }] },
          "speed": { "type": "number" },
          "direction": { "enum": [1, -1] },
          "playMode": { "enum": ["normal", "bounce"] },
          "hover": { "type": "boolean" },
          "intermission": { "type": "number" },
          "themeColor": { "type": "string" }
        },
        "required": ["id"],
        "additionalProperties": false
      }
    },
    "author": { "type": "string" },
    "custom": { "type": "object", "additionalProperties": true },
    "description": { "type": "string" },
    "keywords": { "type": "string" },
    "revision": { "type": "number" }
  },
  "required": ["animations", "version"],
  "additionalProperties": false
}

# Animations

Animations are the primary content of a dotLottie file, stored as Lottie JSON files in the animations/ directory.

# Location and Naming

Location: Must reside in the animations/ folder at the root of the archive.
Naming Guidelines:
- Use descriptive, unique names (e.g., loading_spinner.json).
- Prefer lowercase letters and avoid spaces or special characters except _ and -.
- Must end with the .json extension.

# Format and Referencing

Format: Each file must conform to the Lottie JSON specification (opens new window), ensuring compatibility with Lottie renderers.
Referencing: The id in the manifest’s animations array must match the filename (excluding .json).

Example manifest entry:
```
{
  "version": "1",
  "animations": [
    {
      "id": "loading_spinner"
    }
  ]
}
```
This references animations/loading_spinner.json.

# Multiple Animations

A dotLottie file can contain multiple animations. Each animation must have a unique ID in the manifest and should be stored as a separate JSON file in the animations directory.

By default, the first animation in the manifest will be played by the dotLottie player, but this can be overridden by the activeAnimationId property in the manifest, or by providing a custom API to the dotLottie player.

Note: It's suggested for players to provide a way to set the active animation via the player API, hence the activeAnimationId property is optional.

# Assets

If an animation requires external assets like images, these should be included in the images/ directory and referenced properly within the animation file.

Note: External assets are not mandatory, but it's recommended to extract them from the Lottie JSON file to allow for assets to be reused across animations and further optimizations.

# Images

Location: Stored in the images/ directory.
Supported Formats: Includes PNG, JPG, SVG, WEBP, and GIF.

Referencing: Images are linked in the Lottie JSON via relative paths from the archive root.

Example in animations/animation_1.json:

{
  "assets": [
    {
      "id": "img_1",
      "p": "images/img_1.webp",
      "u": "",
      "e": 0
    }
  ]
}

# dotLottie v1.0 Specification

# File Structure

# Manifest

# Location and Format

# Properties

# Animation Object

# Example

# JSON Schema

# Animations

# Location and Naming

# Format and Referencing

# Multiple Animations

# Assets

# Images

# Optimization

# Examples

# Sample File Structure

animation.lottie

Contents

# Sample Animation with Assets

animation-with-assets.lottie

Contents

# Sample File with Multiple Animations

multiple-animations.lottie

Contents