JSON rules for AI agents

An AI agent can write a whole openCanviz video as JSON for you to import. The quickest route is the opencanviz-json agent skill, which packs the rules on this page, the schema and four tested example projects into one folder. If your tool does not take skills, paste the prompt at the end of this page instead. Import the result from the Create page and play it through before you build on it.

Get the agent skill

Download opencanviz-json.zip. It holds SKILL.md (the instructions), schema.json and an examples folder. Then use it in one of these ways:

• Claude Code: unzip it into ~/.claude/skills/, so you have ~/.claude/skills/opencanviz-json/SKILL.md, or into a project's .claude/skills/ to keep it to that project.
• Claude Code plugin: the skill is also published as a plugin on GitHub at opencanviz/opencanviz-skills-repo. Run /plugin marketplace add opencanviz/opencanviz-skills-repo, then /plugin install opencanviz@opencanviz-skills.
• Claude apps: open Customize > Skills, click +, choose Create skill, then Upload a skill and pick the zip.
• Any other chatbot or agent: paste the contents of SKILL.md into the chat or the agent's instructions, and attach schema.json and an example if the tool takes files.

Then ask, for example, "Make a 60-second openCanviz video as JSON that explains how DNS works."

Agents that read the web can also start from llms.txt, which links these pages, the schema and the skill.

Rules every file must follow

1. Include an artboard with x, y, width, height and background, or the frame can land in the wrong place.
2. Give every scene at least one step. A scene with no steps shows nothing.
3. Give every step a durationMs greater than 0, plus nodes and edges lists.
4. Make step 0 a full snapshot of every node and edge, and make the scene's nodes and edges match it. Nodes that appear later start at opacity 0.
5. Set "delta": true on every later step, and list only id plus the fields that change.
6. Keep ids unique within a scene and the same in every step. Prefix them per scene, such as s1_ and s2_.
7. Point edge from and to only at nodes in the scene's nodes. Other edges are removed when the project opens. An edge to a node added later goes in addEdges.
8. Make every node at least 10 by 10 pixels. Draw lines as edges, not thin boxes.
9. To reveal a node, set its opacity to 1 in that step and add a fadeIn or slide-in action. If you leave it at 0, it fades back out in the next step.
10. To move a node, set its new x and y in the step. For exact timing, add a transformTween whose to has the same values. Its from.x and from.y are ignored.
11. Set edge line width with width. strokeWidth is only for node outlines.
12. Leave out fields the app fills in, such as _addedNodeIds, _animatedProps and recorded audio.
13. Write plain JSON: no comments and no trailing commas.

Common mistakes

Checklist

• The file validates against the schema.
• It has a title and a full artboard.
• Every scene has at least one step, and steps after 0 are deltas.
• Every edge end is a node in the scene.
• Every node is inside the artboard and at least 10 by 10 pixels.
• Every reveal sets opacity 1, and every drawn-in edge ends at trim 1.
• There is one narration clip per step.

A prompt to paste

Use this when your tool does not take skills. Replace the last line with your topic.

You write openCanviz project JSON. Output one JSON object in a single json code block and nothing else.
Follow the schema at https://opencanviz.com/schema/v1.json and the rules at https://opencanviz.com/docs/json-rules-for-ai-agents.
Shape: {"$schema","title","artboard","diagrams":[{"nodes","edges","steps","narration"}]}.
- artboard is required, centered on the origin: 16:9 is {"x":-960,"y":-540,"width":1920,"height":1080}.
- Node x,y is the top-left corner; every node needs id, kind, x, y, w, h and is at least 10x10.
- Step 0 lists every node and edge in full; scene nodes/edges equal step 0. Later nodes start at opacity 0.
- Every later step has "delta": true and lists only id plus changed fields.
- To reveal: set opacity 1 in that step AND add {"type":"visibility","target":{"kind":"node","id":"..."},"mode":"fadeIn","durationMs":400}.
- To draw an edge in: start at trim 0, set trim 1 in the step, add an edgeTween from {"trim":0} to {"trim":1}.
- Edge from/to must be node ids in the scene. Edge line width is "width".
- Each step has durationMs and a caption of 8 to 20 words. Add one narration clip per step:
  {"id":"n0","text":"<caption>","stepIndex":0,"voice":{"provider":"openai","voiceId":"alloy","voiceName":"Alloy"}}.
- Unique ids per scene, prefixed s1_, s2_. No comments, no trailing commas.
Topic: <describe your video here>

For every field, see the schema reference. For complete files to copy, see JSON examples.