# data.json basics

See how a composition, the `data.json` file, is built, what Blitframe checks in it, and how it finds the files it uses. The [composition format reference](/docs/blitframe/data-json-format) documents every supported feature.

Every version has one composition: a `data.json` file at its root. It is in the Lottie format that Blitframe for After Effects and Bodymovin export from [After Effects](/docs/blitframe/after-effects). When you export, keep assets as separate files (not embedded), and keep the folder structure the export produces.

## Anatomy of a composition

This complete `data.json` renders a 5-second 1080p video: a dark background, a logo image and a headline that fades in. It needs a paid plan, since the free trial renders up to 1280×720 ([plan limits](/docs/blitframe/renders#plan-limits)). The version must also contain `images/logo.png`, and Montserrat Bold must be [available](/docs/blitframe/fonts).

```json
{
  "v": "5.12.2", "nm": "Summer sale", "fr": 30, "ip": 0, "op": 150, "w": 1920, "h": 1080, "ddd": 0,
  "assets": [
    { "id": "logo", "w": 400, "h": 400, "u": "images/", "p": "logo.png", "e": 0 }
  ],
  "fonts": { "list": [{ "fName": "Montserrat-Bold", "fFamily": "Montserrat", "fStyle": "Bold" }] },
  "layers": [
    {
      "ty": 5, "ind": 1, "nm": "Headline", "ip": 0, "op": 150, "st": 0, "sr": 1,
      "ks": {
        "a": { "a": 0, "k": [0, 0, 0] }, "p": { "a": 0, "k": [960, 860, 0] }, "s": { "a": 0, "k": [100, 100, 100] },
        "r": { "a": 0, "k": 0 },
        "o": { "a": 1, "k": [
          { "t": 15, "s": [0], "i": { "x": [0.4], "y": [1] }, "o": { "x": [0.6], "y": [0] } },
          { "t": 45, "s": [100] }
        ] }
      },
      "t": { "d": { "k": [{ "t": 0, "s": { "t": "Summer sale", "f": "Montserrat-Bold", "s": 96, "lh": 110, "ls": 0, "tr": 0, "j": 2, "fc": [1, 1, 1] } }] }, "a": [] }
    },
    {
      "ty": 2, "ind": 2, "nm": "Logo", "refId": "logo", "ip": 0, "op": 150, "st": 0, "sr": 1,
      "ks": {
        "a": { "a": 0, "k": [200, 200, 0] }, "p": { "a": 0, "k": [960, 440, 0] }, "s": { "a": 0, "k": [100, 100, 100] },
        "r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 }
      }
    },
    {
      "ty": 1, "ind": 3, "nm": "Background", "ip": 0, "op": 150, "st": 0, "sr": 1, "sw": 1920, "sh": 1080, "sc": "#101725",
      "ks": {
        "a": { "a": 0, "k": [0, 0, 0] }, "p": { "a": 0, "k": [0, 0, 0] }, "s": { "a": 0, "k": [100, 100, 100] },
        "r": { "a": 0, "k": 0 }, "o": { "a": 0, "k": 100 }
      }
    }
  ]
}
```

| Part | Meaning |
|---|---|
| `w`, `h`, `fr` | Canvas size in pixels and frames per second. |
| `ip`, `op` | First frame and the frame after the last. Here 0 to 150 at 30 fps is 5 seconds. |
| `assets` | Files the layers use. An image layer points at an asset through `refId`. The file is `u` + `p` in the version. |
| `fonts.list` | Every font a text layer uses. Text refers to it by `fName`. `GET /v1/fonts` returns a ready-made entry for each library font. |
| `layers` | Each layer has a unique `ind`. A smaller `ind` paints in front, whatever the array order. A layer is visible from its `ip` to its `op`. |
| `ty` | Layer type: `0` precomposition, `1` solid color, `2` image, `3` null (or an adjustment layer, with `ef` and `sw`/`sh`), `4` shape, `5` text, `9` video, `13` camera, `16` 3D model. Sound does not come from layers. It comes from the version's `soundtrack`, set by an edit, or the render request's `audio`. |
| `ks` | The layer transform: anchor `a`, position `p`, scale `s` (percent), rotation `r` (degrees) and opacity `o` (0 to 100). |
| `{"a": 0, "k": value}` | A property that does not change. |
| `{"a": 1, "k": [keyframes]}` | An animated property. Each keyframe has a frame `t` and a value `s`, and `i` and `o` set its easing. The last keyframe holds. |
| `t.d.k[0].s` | The text: `t` string, `f` font name, `s` size, `lh` line height, `j` justification (`0` left, `1` right, `2` center), `fc` fill color as RGB 0 to 1. |

Colors inside shapes and text are arrays of 0 to 1 (`[1, 1, 1]` is white). A solid layer's `sc` is a hex string. The [format reference](/docs/blitframe/data-json-format) covers every layer type, shapes, masks, effects and expressions.

## What Blitframe checks

Whenever a version is created, Blitframe reads its `data.json`. Each check has one of three outcomes:

| Outcome | What happens |
|---|---|
| Reported in `problems` | The version is still created, but its `renderable` is `false`. A render of it is refused with `422 version_not_renderable`. Fix the cause in another edit. |
| Reported in `warnings` | The version renders, but that part renders differently from After Effects, or not at all. |
| Refused | The request fails with a `4xx` [error](/docs/blitframe/errors) and creates nothing. |

Something Blitframe does not check can still make a render fail after it starts. A failed render is refunded, with two exceptions ([pricing](/docs/blitframe/renders#pricing)).

The version's `problems` report anything that would stop a render:

| Field | Requirement |
|---|---|
| `w`, `h` | Width and height, 1 to 16384 pixels, written as whole numbers such as `1920`, not `1920.0`, which the engine reads as 0. Your [plan](/docs/blitframe/renders#plan-limits) may allow less. |
| `fr` | Frame rate, at least 1 and at most 120 (a Blitframe limit). Fractional rates such as 29.97 are accepted and play at that rate. |
| `ip`, `op` | In and out frames. `ip` is 0 or more, and `op` is greater than `ip`. The duration, `(op - ip) / fr`, is at most 3,600 seconds. These are Blitframe rules. |
| `layers` | A list of layer objects. Every layer has a text `nm` and a readable `ks` transform object. A `parent` names the `ind` of another visual layer in the same composition. A `refId` names an asset of the layer's kind. A solid has a text `sc`, and each mask a text `mode`. A camera's `pe`, when present, is an object. See [Layers](/docs/blitframe/data-json-format#layers-ordering-and-relationships). |
| `layers`, reported in `warnings` | These don't stop a render, so they are reported in `warnings` instead: no `layers` list (the render shows nothing), a missing or repeated `ind`, a matte `tp` naming no layer that draws, a non-numeric layer `op`, and a camera without a fixed, nonzero zoom. |
| Precompositions | Every precomposition asset a layer uses has a text `nm`, and none contains itself. One render uses at most 180 precomposition layers that are not collapsed, counting every use inside another precomposition. It uses at most 10,000 precomposition copies in all. Both are Blitframe limits. |
| Video layers | At most 100 video layers per render, counting hidden ones and every use inside a precomposition. |
| Image assets and 3D models | At most 484 textures. Each image asset `id` takes one, whether a layer shows it or not. GIF and WebP files don't count, nor does an asset with a `data:` `p` or a `w` or `h` over 4096. Each 3D model a layer uses adds the textures its materials draw with, and any model adds 3 for 3D lighting ([textures](/docs/blitframe/data-json-format#textures)). |
| Text layers and 3D models | At most 199 meshes per render: one for each text layer, two for a stroked one, and one for each 3D model asset a model layer uses, however many layers show it. Hidden text layers and every copy of a precomposition count. |
| Vector paths | At most 2,000 per render: shape paths, masks, and fills cut by Trim Paths. Shape paths and masks count in hidden layers too, and fills cut by Trim Paths only on layers that show. Every copy of a precomposition counts ([vector paths](/docs/blitframe/data-json-format#vector-paths)). |
| Shapes and text | Every shape layer has a path followed by a fill or stroke that draws. Its items and values are in forms the engine can read: a rectangle without its size `s` would fail the render. Text layers that draw have visible text in a declared font. A field the engine reads differently, such as a justified alignment, is reported in `warnings`. Paths and paints past a group's limits are skipped and reported in `warnings`. See the [format reference](/docs/blitframe/data-json-format#shapes-and-paints). |
| Image and video assets | Every image, video and model asset has a text `id`. Declare `w` and `h` at most 4096 pixels each. The engine skips a larger asset, which is reported in `warnings`, and a layer that shows it is reported in `problems`. A video draws at its declared size, so a video without them is reported in `warnings`. |
| `assets[].u` + `assets[].p` | Every image, video and model asset is a file in the version. |
| `fonts.list` | Every font a text layer uses is available. See [Fonts](/docs/blitframe/fonts). |
| Text encoding and nesting | `data.json` is valid UTF-8. That Blitframe rule keeps names and text readable in your stored versions and in the console. An unpaired surrogate escape, which the engine cannot read, is reported in `problems`. Blitframe reads lists and objects nested at most 255 levels deep. A key repeated in one object is reported in `warnings`, and the engine reads its first value. |

## Asset paths

An image asset in `data.json` looks like this:

```json
{ "id": "image_0", "w": 800, "h": 600, "u": "images/", "p": "img_0.png", "e": 0 }
```

Blitframe joins `u` and `p` (`images/img_0.png`) and looks for that path in the version. If no path matches exactly, it looks for one that differs only in letter case. Then it looks for the file name alone, if only one file has that name.

A `data:` URI in `p` is not supported. The engine skips that asset, which is reported in `warnings`, and a layer that shows it is reported in `problems`. Add the file to the version and reference it with `u` and `p`.

The `e` flag is not read. An asset whose `p` names a file in the version renders, whatever `e` says.

## Editing the composition

To change text, colors, timing or images, edit `data.json` and send it in an [edit](/docs/blitframe/projects#editing-a-project), which creates a new version. Read [Editing a composition](/docs/blitframe/data-json-format#editing-a-composition-through-blitframe) first. A few tips:

- Text is in text layers (`"ty": 5`), under `t.d.k[].s.t`.
- To change only text, fonts, images or video, use [replacements](/docs/blitframe/editing#replacements). They change a layer without sending `data.json`, and fit new images for you.
- To swap an image by hand, add a new file at the same path. Or add it under a new path and change the asset's `p`. The image renders at the asset's `w` and `h`, so a file of another size is stretched. Update `w` and `h`, and the anchor, when the new file's size differs.
- Every edit keeps the previous version, so you can [undo](/docs/blitframe/projects#undoing-a-change) it. To try an alternative without changing the template, [duplicate the project](/docs/blitframe/projects#duplicating-a-project), or render it with [replacements](/docs/blitframe/editing#in-a-render).

To read a version's `data.json`, send `GET /v1/versions/{id}/files/data.json`. It redirects (`302`) to a download link for a file of any size, so follow the redirect (`curl -L`). Agents can also use the `read_file` MCP tool, which reads JSON files up to 5 MB.
