How to Validate VideoJSON Before Rendering in an AI Agent

Question

AI video agents often fail late. A prompt produces a plausible storyboard, the renderer starts, and only then do we discover an inaccessible asset, text that cannot fit, or a timeline whose scenes do not add up. Late failures waste compute and make autonomous repair difficult.

A better pipeline validates the canonical composition before a render job is accepted. This tutorial shows the validation layers that make a VideoJSON workflow predictable.

1. Validate the document boundary

Treat VideoJSON as an API contract, not as an informal object. Reject unknown layer types, missing required fields, invalid numeric ranges, and unsupported easing names. A composition should explicitly declare its dimensions, frame rate, duration, scenes, and layers.

A useful validator returns structured issues with four fields: code, path, message, and an optional repair instruction. The path identifies the exact scene or layer. The repair gives an AI agent a permitted next action instead of forcing it to interpret a stack trace.

2. Prove timeline consistency

The total composition duration must equal the sum of scene durations. Every layer start time must be non-negative, and a layer cannot extend beyond its scene unless the format explicitly permits it. Audio should span the intended timeline exactly.

Check transitions as part of the calculation. If a renderer overlaps two scenes during a transition, define whether that overlap changes the logical duration. The same rule must be used by the planner, validator, preview, and final renderer.

3. Validate text as layout

A string being present does not mean it will render safely. Each display text layer should define a maximum width and maximum line count. Measure the selected font at the authored size, apply safe-area margins, and use a deterministic autofit policy.

A practical policy is:

1. Wrap text at the configured width.
2. Reduce the font size only to an approved minimum.
3. Truncate with an ellipsis if it still exceeds the line budget.
4. Return a warning when truncation changes meaningful copy.

For text over imagery, validate contrast or require an overlay. The result should not depend on a lucky background frame.

4. Inspect media before queuing

Resolve each image, video, and audio source before the job is submitted. Confirm that the URL is reachable, the content type is allowed, and basic metadata can be read. Reject local file URLs or transient blob URLs in remote jobs.

For video and audio, check duration and codec compatibility. For images, verify dimensions and guard against extreme aspect ratios that will crop important content.

5. Restrict animations and effects

Validate every transition and easing against a known registry. Unknown animation names should not silently fall back to linear motion because that hides planner errors.

Effects need bounded parameters. Blur radius, distortion strength, opacity, and color values should have documented ranges. If the renderer supports multiple backends, validate that the selected effect exists on the intended backend.

6. Make validation deterministic

The same input and validator version should produce the same ordered list of issues. Avoid checks that depend on the current locale, random sampling, or changing network responses without recording evidence.

Persist the composition hash, validator version, asset metadata used during validation, all warnings and errors, and the repaired revision when an agent changes the document. This history makes regressions explainable.

7. Separate errors from warnings

Errors block rendering: missing assets, invalid timing, unsupported layer types, or impossible dimensions. Warnings request review: minor text truncation, very dense motion, or a low-contrast region that still meets the minimum threshold.

An autonomous agent may repair errors automatically when the repair contract is explicit. Warnings should be included in preview evidence so a human or higher-level policy can decide.

8. Revalidate after every repair

A repair can introduce a new failure. Shortening one scene may break the total duration; replacing a font may change line wrapping. Run the full validator after every material change and cap repair attempts to prevent loops.

The final accepted revision, not the first generated draft, must be the document attached to the render job.

9. Connect validation to the render API

Submit only validated compositions. Use an idempotency key derived from the logical request, and include the composition hash in job metadata. If the payload changes after repair, create a new revision while preserving the request lineage.

The render worker should still defend itself, but validation at the boundary prevents predictable failures from consuming queue capacity.

Production checklist

Before rendering, confirm:

• the schema and layer types are valid;
• scene and layer timing is consistent;
• text fits its width and line budget;
• media is reachable and compatible;
• transitions, easings, and effects are supported;
• the composition hash and validator version are recorded;
• all blocking issues are resolved;
• preview evidence belongs to the exact accepted revision.

iLoveVideoEditor uses this contract-driven approach for deterministic VideoJSON rendering and exposes focused MCP operations for AI agents.

Learn more: https://ilovevideoeditor.com/?utm_source=coderlegion&utm_medium=tutorial&utm_campaign=videojson_validation

Open-source MCP server: https://github.com/ilovevideoeditor/mcp-server?utm_source=coderlegion&utm_medium=tutorial&utm_campaign=videojson_validation

Disclosure: This original tutorial was prepared by the iLoveVideoEditor team and describes engineering practices used in our video automation workflows.