YADL syntax and capability reference
Versioned reference for YADL grammar constructs and their editor, validation, preview, and export behavior.
YADL syntax and capability reference
Reference version: yadl-capability-reference-v1
Grammar fingerprint: c1b57cd7a138409c162273daf5f6451072e3e6ec73cc83844ff7cb31082062e5
This is the concise contract for the current YADL language. It is generated from the checked-in Langium grammar and is checked by pnpm yadl:capabilities:check. Use it to decide which syntax is appropriate for a document; use the AI-safe profile when an integration needs the narrower certified subset.
Document skeleton
meta, imports, reusable declarations, one or more diagram or scene blocks, and an optional export video block form a document. Statements are block-oriented and use explicit names, strings, durations, coordinates, and references.
export video { fps 30 viewport (1920, 1080) format mp4 }
style card { background-color: "#0f172a"; color: "#ffffff"; }
scene intro "Welcome" {
diagram "Welcome" type flowchart {
Start: { text "Start" at (120, 180) size (220, 120) style card }
Finish: { text "Finish" at (480, 180) size (220, 120) style card }
Start -> Finish: { type smoothstep marker-end arrowclosed }
timeline story duration 4s {
action reveal after 0s { show Start using fadeIn for 500ms }
stop after 1s cue "Introduce the first step" emphasis
}
}
}Capability matrix
| Area | Primary syntax | Validation | Editor support | Preview and export | Notes |
|---|---|---|---|---|---|
| Document metadata and imports | meta, import, export { ... } from | Yes | Completion and diagnostics | Resolved imports participate in preview/export | Import paths and entitlement still apply. |
| Reusable design system | var, alias, style, paint, brand, layer | Yes | Completion and formatting | Yes | Prefer named styles and brands for portable source. |
| Diagrams and scenes | diagram, scene, positions, elements, connections | Yes | Completion, source reveal, Pixi editing | Yes | Built-in diagram types: architecture, sequence, class, activity, state, usecase, component, deployment, communication, package, flowchart, erd, bpmn, c4, network, orgchart, mindmap, timeline, gantt, wireframe, chart. |
| Reusable visuals | component, background, group, use | Yes | Completion and catalog/editor workflows | Yes when dependencies resolve | Keep published component source separate from documents. |
| Media and accessibility | icon, image, video, audio, svg, aria-label | Yes | Common snippets and diagnostics | Subject to browser/origin/media availability | Preview availability does not bypass export preflight. |
| Charts | chart, chart-group, series, data, options | Yes | Chart snippets and timeline support | Yes | Supported chart kinds are area, bar, line, pie, radar, radial, and tooltip. |
| Motion and timeline | timeline, action, animate, show, hide, media/camera/filter statements | Yes | Timeline authoring and source reveal | Yes | Timed actions affect normal preview and video export. |
| Presenter cues | `stop after <duration> cue "..." [emphasis | warning]` | Yes | Timeline stop lane, cue snippets, teleprompter | No |
| Video configuration | export video { fps ... viewport/layout ... format ... } | Yes | Export readiness diagnostics | Yes | Valid formats and preset/frame compatibility are enforced separately. |
Canonical rules for people and agents
- Use quoted strings for displayed text, URLs, CSS-like values, and cue text.
- Use named declarations and references instead of duplicating styling or coordinates where possible.
- Keep timeline delays explicit. Use
after previousonly when the relative relationship is intentional. - Validate after source changes; successful parsing alone does not guarantee a resolved dependency, an export-ready frame, or media availability.
- Presenter cues belong only on
stop after <duration>entries. A cue is plain text;emphasisandwarningare the only supported cue intents.
Advanced and experimental surface
The following grammar-supported forms are intentionally more flexible and should be used with focused preview/export checks instead of as a default for generated source:
- HTML-like component/background trees and free-form CSS strings.
- Custom
animation gsap { ... }property blocks. - Raw SVG and remote media, which remain subject to SVG safety checks, source-origin policy, and renderer compatibility.
- Diagram-family-specific statements and chart options beyond the canonical examples.
For a dependable automated workflow, start with the Agent API reference and its certified explanatory profile. That profile is deliberately smaller than this full grammar.