YAML DSL form runtime — definitions in git, compiled bundles in production

frameworkactive owner: philip · updated 2026-11-14

relates: dsl-compiler-never-distributed · fail-safe-decision-table

YAML DSL form runtime — definitions in git, compiled bundles in production

Forms and applications are defined as YAML DSL documents (UIForm DSL v2, qform/qapp) versioned in git, compiled to self-contained JavaScript bundles, and distributed as static assets. The DSL never leaves the repo; consumers run only the compiled bundle and submit to a seam endpoint.

Problem it solves

• Hand-built forms per customer don't scale; letting customers edit raw JSON/YAML invites breakage; shipping the DSL + compiler to consumers gives away the IP. A compiled-bundle model keeps definitions versioned and reviewable while protecting the compiler.

Shape

• DSL docs in git: groups → pages → fields, constraints, conditional visibility, hooks, API-submission actions. YAML diffs cleanly in PRs — hundreds of forms stay reviewable.
• Compiler (Go form-engine, Python form-edit-custom editor) renders DSL → JS bundle (render + validate + collect + submit inlined, no runtime DSL fetch).
• Submission seam: bundle POSTs to an endpoint that works standalone (SQLite/file store) or serverless (DynamoDB) via env-selected adapters; file uploads via presigned R2 URLs (multipart, part-level resume).
• Editor is a separate surface (visual editor + YAML editor + live preview) that writes DSL back to git — never edits bundles.

Rules

• The compiler, DSL schemas, and DSL source never ship to consumers — only compiled bundles (see kb:dsl-compiler-never-distributed).
• Bundles are fully self-contained; source maps are never published.
• Every form change is a git PR through the compile/validation gates — no out-of-band edits.
• Submission payloads are versioned contracts; the endpoint accepts only contracts it knows.
• Conditional logic and validation live in the DSL (compiled into the bundle), not in per-form custom JS.

Anti-patterns

• Runtime interpretation of DSL in the browser (exposes the schema, slower, harder to gate).
• Form definitions stored in a database instead of git (loses PR review, blame, and compile gates).
• Per-form bespoke JavaScript escaping the DSL (drift, unreviewable).
• Uploads proxied through the app server (use presigned object storage instead).

Sources

• factory/forms/form-engine (Go DSL engine), factory/forms/form-edit-custom (Python editor)
• app-builder UIForm DSL v2 (renderer.js/editor.js) — repo not cloned locally; index in machine/code/
• knowledge-base/decisions/dsl-compiler-never-distributed.md