YADL source language

YADL documents are human-readable source files, not JSON schemas. The editor validates source while you work and turns it into the visual preview, timeline, image exports, and video exports.

Document model

A document normally defines an output frame, paints and styles, then one or more scenes containing diagrams, elements, connections, and optional timeline actions. Names such as Plan, Build, and Share identify editable visual elements and can be used by animation actions.

Start with the editor when you are learning the syntax: diagnostics explain the source location and the preview updates from the same document. A valid video document needs a video block, a positive timeline duration, and a frame compatible with the selected export preset.

A complete, self-contained example

This verified example produces a square, ten-second animated process flow. Paste it into a new document in the editor to explore the source and preview together.

export video { fps 30 viewport (1080, 1080) format mp4 }
paint Paper { color "#f8fafc" }
paint Ink { color "#0f172a" }
paint Blue { color "#0369a1" }
brand AgentBaseline {
  paints { background.page = Paper text.body = Ink text.title = Ink brand.primary = Blue }
  typography {
    title { font "Arial" size 48 fontWeight 700 }
    body { font "Arial" size 30 }
  }
}
brand AgentBaseline
background { div { style = "width:100%;height:100%;background:var(--theme-background)" } }
style card { background-color: "#0369a1"; color: "#ffffff"; border-radius: "16px"; font-size: "30px"; }
style accent { background-color: "#0d9488"; color: "#ffffff"; border-radius: "16px"; font-size: "30px"; }

scene story "From idea to delivery" {
  diagram "From idea to delivery" type architecture {
    text heading { "From idea to delivery" as title at (80, 70) size (920, 90) }
    text description { "Follow one clear path." as body at (80, 165) size (920, 80) }
    Plan: { text "Plan" at (100, 280) size (240, 150) style card }
    Build: { text "Build" at (420, 280) size (240, 150) style card }
    Share: { text "Share" at (740, 280) size (240, 150) style accent }
    Plan -> Build: { type smoothstep marker-end arrowclosed color slategray thickness 4 }
    Build -> Share: { type smoothstep marker-end arrowclosed color slategray thickness 4 }
    timeline story duration 10s {
      action reveal1 after 0ms { show Plan using fadeIn for 600ms }
      action reveal2 after 900ms { show Build using fadeIn for 600ms }
      action reveal3 after 900ms { show Share using fadeIn for 600ms }
    }
  }
}

Reusable source

Use Components for published, versioned reusable modules and Templates for an editable starting document. Keep the source that you save with a project separate from a published catalog component: changing a saved document never mutates the catalog version.

When an integration uses the Agent API, validate the workspace before saving or rendering it. The verified agent profile currently accepts self-contained or local multi-file workspaces; catalog dependencies and imported assets are reported as unsupported for that profile. The editor can still use YADL features outside that limited integration profile.

Validate before delivery

Use the editor diagnostics for ordinary creation. Developers can use POST /api/v1/agent/validate and POST /api/v1/agent/inspect through the documented Agent API to receive structured validation issues, calculated duration, frame metadata, and visual bounds. Those endpoints do not repair or silently rewrite a document.