formspec-local

Formspec

A declarative form specification where structure, behavior, and presentation are independent, composable JSON documents.

Built by Michael Deeb, TealWolf Consulting with Focus Consulting as a strategic partner. Free and open source under the AGPL-3.0 License.

Website · Features · Architecture · Blog · About

---

Formspec separates what data to collect from how it behaves from how it looks. A single definition drives validation, computed fields, conditional logic, and repeatable sections across any runtime — browser, server, mobile, offline. Every artifact is a JSON document backed by a JSON Schema, so the entire system is machine-readable.

Architecture

The Specification as Abstraction Boundary

Formspec inverts the usual dependency between frontend and backend. Neither implementation knows about the other; both depend inward on the specification:

                  ┌─────────────────────────────┐
                  │     Formspec Specification    │
                  │                               │
                  │  schemas/    (structural truth)│
                  │  specs/      (behavioral truth)│
                  │  FEL grammar (expression truth)│
                  └──────────┬──────────┬─────────┘
                             │          │
              ┌──────────────┘          └──────────────┐
              ▼                                        ▼
   ┌─────────────────────┐    ┌────────────────────────────────────┐
   │  TypeScript Engine   │    │  Rust Shared Kernel                 │
   │                      │◄───│                                     │
   │  Reactive signals    │WASM│  FEL runtime (rust_decimal)         │
   │  4-phase processing  │    │  Assembler, path utils              │
   │  Live state mgmt     │    │  Definition evaluator               │
   │                      │    │  8-pass static linter               │
   └──────┬───────┬───────┘    │  Mapping engine, registry,         │
          │       │            │  changelog, changeset analysis     │
          │       │            └──────────┬────────────────────────┘
          │       │                       │ PyO3
          │       │            ┌──────────▼───────────────┐
          │       │            │  Python Implementation    │
          │       │            │                           │
          │       │            │  Format adapters (JSON,   │
          │       │            │    XML, CSV)              │
          │       │            │  Artifact orchestrator    │
          │       └────────┐   └──────────────────────────┘
          │  (presentation)│  (authoring)
          ▼                ▼
   ┌──────────────────┐    ┌─────────────────────┐
   │  Web Component    │    │  Studio Core         │
   │                   │    │                      │
   │  <formspec-render>│    │  Command model       │
   │  35 plugin types  │    │  Queries & diagnostics│
   │  Theme resolver   │    │  Undo/redo, replay   │
   └──────────────────┘    └──────────┬────────────┘
                                      │
                        ┌─────┬───────┼───────┬──────┐
                        ▼     ▼       ▼       ▼      ▼
                      MCP   Chat   CLI tool  Studio  LLM

The specification — 19 JSON Schemas, normative prose, and FEL grammar — is the stable abstraction that all implementations conform to. A Rust shared kernel (7 crates, ~47,000 lines, 1,462 tests) owns all spec business logic: FEL evaluation, assembly, linting, mapping, registry, changelog, and definition evaluation. The TypeScript engine keeps Preact Signals for reactive UI state and calls Rust via WASM. Python calls Rust via PyO3. One implementation, every platform.

This inversion runs deeper than just client/server. The TypeScript side itself has two dependency boundaries below the engine:

The web component is a presentation adapter — it reads engine signals and dispatches to a plugin registry. Each input component uses a headless behavior/adapter split: behavior hooks own reactive state and ARIA management, render adapters own DOM structure. The default adapter reproduces standard Formspec markup; design-system adapters in formspec-adapters provide alternative DOM without touching behavior. The engine drives any rendering surface: a React component tree (via formspec-react), a SwiftUI form (via formspec-swift), a PDF generator, or a server-rendered page. Build a new presentation layer by subscribing to engine signals; the behavioral core stays constant.