Designing a Maintainable Video JSON Schema

JSON gives applications and AI agents a precise way to describe video, but a valid document is not automatically a maintainable one. Good schemas separate reusable resources from scene instructions, make timing easy to inspect, and keep dynamic values within safe bounds.

Start with three layers

RenderingVideo schemas have three top-level areas:

• meta defines the canvas, frame rate, background, and descriptive information.
• assets provides optional reusable fonts, images, videos, audio, subtitles, models, and SVG resources.
• tracks contains the timed clips that appear in the composition.

{
  "meta": {
    "version": "2.0.0",
    "title": "Weekly report",
    "width": 1920,
    "height": 1080,
    "fps": 30,
    "background": "#0B1020"
  },
  "assets": {
    "images": [{ "id": "logo", "src": "https://cdn.example.com/logo.png" }]
  },
  "tracks": [
    {
      "id": "titles",
      "clips": [
        {
          "type": "image",
          "src": { "$ref": "logo" },
          "start": 0,
          "duration": 5,
          "transform": { "x": 0, "y": -300, "width": 240, "height": 80 }
        }
      ]
    }
  ]
}

Use assets for identity, clips for behavior

A shared logo or font belongs in assets; its position and timing belong in a clip. Referencing assets by ID prevents long URLs from being copied throughout the document and makes replacements safer.

Use stable, descriptive IDs such as brand-logo, music-bed, and subtitles-main. Avoid IDs tied to array positions or temporary database rows.

Make time obvious

Every clip should have an intentional start and duration. Organize tracks by responsibility, such as background, media, titles, captions, and overlays. This does not change visual stacking by itself, but it makes reviews and debugging much easier.

For generated content, derive scene boundaries once and pass them to every related clip. Avoid independently adding decimal durations across many objects; small rounding errors can create flashes or gaps.

Keep dynamic input constrained

Treat product names, prices, colors, media URLs, and subtitle words as data. Treat clip types, layout rules, and animation choices as template logic. Validate every dynamic string and number before merging it into the schema.

Useful limits include maximum text length, allowed color formats, public HTTPS asset URLs, positive dimensions, and maximum video duration. Generate a fallback when optional content is missing.

Prefer small compositions

A clip can support animations and keyframes, but placing every behavior into one giant object makes changes risky. Split independent visual ideas into separate clips and tracks. Reuse templates for repeated structures such as title cards, product grids, and caption treatments.

Validate against the deployed renderer

Schema support evolves. Query GET /api/v1/capabilities in authenticated workflows and use the public preview endpoint for visual validation. Static type definitions catch shape errors; a real preview catches font metrics, remote asset behavior, and timing problems.

Version the schema with your product

Store the source schema, the template version, and the business input used to produce it. If a customer reports a problem, you should be able to reproduce the exact output rather than regenerating it from today's template.

A maintainable video schema is more than a payload. It is an editable artifact, an audit record, and a stable interface between product data and the renderer.

Explore the full JSON field reference or edit working schemas in the Playground.