Formspec v1.0 Draft

A JSON-native declarative form standard

Core Specification

Formspec v1.0 — Core Specification Normative

The complete form standard: conceptual model, FEL expression language, definition schema, advisory presentation hints (widget, layout, accessibility), validation, versioning, extensions, and lineage.

4,740 lines ~27,800 words 9 sections + Appendix A
Companion Specifications

Mapping DSL v1.0 Companion

Bidirectional data transformation between Formspec Responses and external system schemas (JSON, XML, CSV). 10 transform types, array operations, conditional mapping, format adapters.

1,998 lines ~11,900 words 8 sections + Appendix A

FEL Normative Grammar Normative

The normative PEG grammar for the Formspec Expression Language. Supersedes the informative §3.7 grammar. Adds comments, escape sequences, object literals, let expressions.

376 lines ~2,050 words

Changelog Format v1.0 Companion

Machine-readable diff format for Definition versions. Impact classification, generation algorithm, and auto-migration from change hints.

244 lines ~1,400 words

Extension Registry v1.0 Companion

JSON document format for publishing, discovering, and validating Formspec extensions. Naming rules, lifecycle model, well-known URL discovery, and conformance requirements.

512 lines ~3,100 words

Theme Specification v1.0 Companion

Sidecar theme documents for visual presentation: design tokens, widget catalog with typed configs and fallback chains, 3-level selector cascade, 12-column responsive page layout.

1,082 lines ~6,300 words 9 sections + 3 appendices

Component Specification v1.0 Companion

Tier 3 presentation tree with slot binding: 18 core and 16 progressive components, parameterized custom templates, conditional rendering, responsive prop overrides, and design token integration.

3,224 lines ~18,500 words 13 sections + 3 appendices

References Specification v1.0 Companion

Standalone sidecar for attaching documentation, regulatory guidance, knowledge bases, and AI agent data stores to any field in a definition. Audience-aware (human, agent, both), composable overlays, URI schemes for vector stores and knowledge bases.

697 lines ~6,500 words

Ontology Specification v1.0 Companion

Standalone sidecar for binding form fields to external ontologies (schema.org, FHIR, ICD-10, Dublin Core). Concept bindings, vocabulary alignment with SKOS relationship types, cross-form data alignment, and JSON-LD context generation.

782 lines ~5,100 words

Locale Specification v1.0 Companion

Standalone sidecar for internationalization: translated labels, help text, error messages, option labels, and content blocks. Multiple locales per form, independently versioned, with plural-form support and RTL layout hints.

1,230 lines ~6,200 words
JSON Schemas
definition.schema.json — FormDefinition validation schema (draft 2020-12)
277 lines
response.schema.json — Response validation schema (draft 2020-12)
validationReport.schema.json — Standalone Validation Report schema (draft 2020-12)
49 lines
mapping.schema.json — Mapping DSL validation schema (draft 2020-12)
445 lines
registry.schema.json — Extension Registry document schema (draft 2020-12)
148 lines
theme.schema.json — Theme document validation schema (draft 2020-12)
341 lines
component.schema.json — Component document validation schema (draft 2020-12)
636 lines
references.schema.json — References document validation schema (draft 2020-12)
ontology.schema.json — Ontology document validation schema (draft 2020-12)
locale.schema.json — Locale document validation schema (draft 2020-12)
Reference Implementation

Python API Reference Companion

Generated API docs for the Python reference implementation: FEL evaluator, static linter, mapping engine, adapters, changelog, and registry.

6 packages 34 modules

FormEngine API TypeScript

Core form state management: FormEngine class, FEL lexer/parser/interpreter, path resolution, validation, and reactive signals.

Web Component API TypeScript

FormspecRender custom element, ComponentRegistry, theme resolver, and RenderContext for DOM binding.

Project Core API TypeScript

RawProject, IProjectCore interface, 17 handlers, normalization, page resolution, theme cascade, and component document management.

MCP Server API TypeScript

28 structured tools for LLM-driven form authoring via Model Context Protocol (stdio transport).

Chat Adapter API TypeScript

AIAdapter interface, ChatSession, scaffolding templates, and conversational form builder logic.

fel-core Rust

FEL lexer, parser, evaluator (base-10 decimal), environment, extensions, dependency extraction, and AST printer.

formspec-core Rust

FEL analysis, path utilities, schema validator, extension analysis, runtime mapping, assembler, registry client, and changelog.

formspec-eval Rust

Definition evaluator — 4-phase batch processor with topological sort, inheritance, NRB, and wildcard support.

formspec-lint Rust

7-pass static linter — 35 diagnostic codes, pass gating, authoring and runtime modes.

Source Files
spec.md
Markdown
mapping-spec.md
Markdown
fel-grammar.md
Markdown
changelog-spec.md
Markdown
extension-registry.md
Markdown
component-spec.md
Markdown
references-spec.md
Markdown
ontology-spec.md
Markdown
locale-spec.md
Markdown