Validation and schema

Why validation matters

Validation makes the document predictable for both people and AI agents. It checks that the JSON uses the documented Neonix JSON V2 vocabulary, that values have the right types and that references point to real objects.

Unknown properties, invalid values and broken references are rejected before a project is accepted.

Minimal valid document

{
  "format": "motion-protocol",
  "formatVersion": 2,
  "composition": { "width": 1080, "height": 1080, "fps": 30 },
  "assets": [],
  "layers": [],
  "audio": { "sampleRate": 48000, "tracks": [] }
}

The root object must identify the document format and version, then provide a composition, an asset list, a layer list and an audio section. Optional features can be added only with documented fields.

Required root fields

Field	Purpose
`format`	Must be `motion-protocol`.
`formatVersion`	Must be `2`.
`composition`	Defines width, height, frame rate and optional background/color settings.
`assets`	Declares reusable image, video, audio and font resources.
`layers`	Defines the visible hierarchy and timed visual content.
`audio`	Defines audio settings and tracks, including an empty list when no audio is used.

What is checked

exact format and formatVersion;
required fields and their expected JSON types;
finite numbers, supported units, valid colors and documented enum values;
positive composition dimensions and a valid frame rate;
unique asset, layer, definition, track and clip ids;
valid group parents, no cycles and stable sibling order;
valid image, video, audio and font asset references;
valid paint, marker, clipping, mask and effect references;
animatable property paths, typed values and keyframe bounds;
video trim, source duration and audio fade bounds.

IDs and references

Use short, stable and unique ids. An id may be referenced by another object, so changing it requires updating every reference to it.

Before submitting a document, verify that:

each assetId, parentId or definition reference resolves;
a layer does not point to itself as a parent;
group relationships do not form a cycle;
sibling order is not duplicated or ambiguous;
a paint or effect reference uses the correct documented kind.

Values and timing

Numbers must be finite JSON numbers. Do not use NaN, Infinity, numeric strings or browser expressions. Colors must use a documented color format, and enum values are case-sensitive.

For timed content, keep these values coherent:

start and end values must describe a non-negative range;
keyframes must use the type expected by the animated property;
video clips must stay within the source duration;
audio fades must stay within the clip range;
transforms and effects must use the units documented for that property.

Common validation errors

Error	Typical cause	Fix
Unknown field	A property was copied from another format or invented by an agent.	Remove it or replace it with the documented JSON V2 field.
Invalid type	A number, boolean or object was sent as a string.	Use the required JSON type.
Duplicate id	Two objects share the same id.	Give each object a unique id and update references.
Missing reference	A layer or clip refers to an asset or definition that is not present.	Add the object or correct the reference.
Invalid range	A time, trim or fade value is outside its allowed range.	Compare it with the composition or source duration.
Unsupported value	An enum, effect or property is outside the documented vocabulary.	Use a supported value or simplify the document.

AI authoring checklist

When an AI creates a document, it should:

Confirm the composition size, frame rate and intended duration.
Create the required root fields before adding optional features.
Generate unique ids and resolve references after all objects are created.
Use only fields and enum values described in the public JSON V2 documentation.
Check media duration, video trims, audio fades and animation ranges.
Keep numeric values as numbers and preserve the expected object shape.
Validate the complete document before presenting it as ready for preview or export.

Validation reports document problems; it does not invent missing assets, silently change unsupported values or guess the author's intended timing.