data.json basics
View as MarkdownSee 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 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. 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). The version must also contain images/logo.png, and Montserrat Bold must be available.
{
"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 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 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).
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 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. |
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). |
| 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). |
| 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. |
| 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. |
| 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:
{ "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, which creates a new version. Read Editing a composition first. A few tips:
- Text is in text layers (
"ty": 5), undert.d.k[].s.t. - To change only text, fonts, images or video, use 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'swandh, so a file of another size is stretched. Updatewandh, and the anchor, when the new file's size differs. - Every edit keeps the previous version, so you can undo it. To try an alternative without changing the template, duplicate the project, or render it with replacements.
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.