Decl Documentation

Describe your data. Decl is a semantic modeling language for structured data: types, values, relationships, constraints, and diagnostics in one executable model.

Start with Why Decl, follow the Service Graph walkthrough, then explore identity and relationships and the hardware interconnect. The positioning document records the four core messages and the evidence behind them. The specification below owns the exact rules.

Status: v0.4.6 (2026-09-08) — v0.1 frozen 2026-08-31, revised through the v0.2 cycle (D31–D33, D29 amended, clarifications), v0.3 (member kinds read off ? and = e with no const in record bodies, D4 amended; hidden members x$ = e, D34), v0.4: rendering is tooling, declared in the module with @render (D35; the E7xxx band, documents in YAML), then v0.4.1: a record flows into a map (D36) and v0.4.2: $referrers answers in rounds (D26 amended), v0.4.3: std.array grows sort / sort_by / unique / reverse, v0.4.4: a computed document binds at its site (D31 amended), v0.4.5: discrimination is hierarchical (D11 amended), v0.4.6: a match subject is a value position (D26 amended) — see REVISIONS.md. The normative specification below is the single source of truth for every implementation phase.

Post-freeze changes are revisions: a change touches the design charter (a new or amended decision), every affected chapter, and REVISIONS.md — in one commit. Divergence between charter and chapters remains a defect to fix on sight (§1.4).

Index

Design documents (why the language is shaped this way)

Document	Description
00. Vision and Background	Why this language exists: the config-language landscape, the agent-era turn, lessons and defect review from the previous Decl iteration, and the checklist of issues the new spec must resolve (informative)
01. Design Requirements	Goals, non-goals, capability requirements (describe / generate / validate / modules / tooling), the generality benchmark, and the quality bar — with the vision checklist promoted to requirements
02. Design Decisions	The charter: principles P1–P7, decisions D1–D36, the rejected-syntax table, the comprehensive example, vision-checklist traceability, and the revision-tracked decision log — spec chapters must not contradict it
03. v0.2 Revision Candidates	Findings from implementing Phases 2–4 and the Phase 5 real-world sweeps, adjudicated 2026-09-01 into revisions v0.1.4–v0.1.8 (the v0.2 cycle); each entry records its outcome
04. Describe your data	Current positioning: the four core messages, proof examples, documentation journey, and application boundaries (informative)

Language specification (normative — the single source of truth)

Chapter	Contents
01. Introduction	What Decl is, core concepts, authority and precedence, conformance, chapter map
02. Lexical Structure	Source text, comments, identifiers, keywords, literals, separators, operators
03. Type System	All type forms, dimensions/units, subsumption (⊑), assignability, uninhabited types
04. Expressions	Operator precedence, arithmetic and numeric safety, match, comprehensions, absence, pipeline, with
05. Declarations and Schemas	const/func/type/output/input, the four member kinds and hidden members, constraint-member placement, inheritance, annotations
06. Constraints and Diagnostics	assert/when, diagnostic templates, type-level else, severities, invalidation and root-cause reporting, paths and ordering
07. Relationships	Composition vs reference, canonical paths and their order, context variables, reference construction and integrity, $referrers
08. Modules and Packages	Exports/imports/re-export, provenance rules, decl.toml, the lock file, multi-module evaluation
09. Evaluation Semantics	Pipeline, dependency graph, laziness, determinism and numeric rules, invalidation, partial evaluation, termination
10. Data Interchange	Input binding, serialization policy, canonical JSON text, total round-trip idempotence, JSON-only scope
11. Grammar	The formal grammar (EBNF): declarations, types, members, expressions, data documents, disambiguation notes — wins over prose on conflict
12. Errors and Diagnostic Codes	Code scheme and bands, machine-readable report format, ordering and conformance scope, the append-only registry
13. Standard Library	The complete std.* surface: array/math/int/float/string/object/map functions, the SI unit catalog, reserved std.graph

Guide (informative)

Document	Description
Why Decl	Describe your data: one semantic model, tree structure and graph relationships, identity, and a small deterministic core
Decl by Example	One scenario end to end — describe → generate → validate — with the evaluated JSON and the diagnostics it produces
Validating Documents	Tutorial: a machine inventory schema, a document that passes and one that does not, and how to read the report — root causes, paths, severities
Generating Configuration	Tutorial: a cluster laid out by a constructor function and a comprehension, summarized by derived members, and re-layered with with
Quantities and Units	Tutorial: dimensions and units of your own, quantity arithmetic, and documents that speak in kilometres and hours
Modules and Packages	Tutorial: the service-graph example split across three modules, and a package with a manifest, a dependency, and a lock file
Identity and relationships	Runnable proof of equal content and distinct reference targets; canonical-place identity, integrity, and reverse queries
Using the semantic model	Decl for AI agents and conceptual models: applications of current capabilities, their boundaries, and evidence before expansion

Tooling (informative)

Document	Description
01. Command line	decl check / evaluate / validate / fmt: universes, --input / --output, diagnostics and the --json report, exit codes
02. REPL	decl repl: a session over the evaluation universe — bare expressions as partial evaluation, session outputs, document edits with exact undo/redo, incremental re-evaluation, and the commands that mirror the CLI verbs
03. Language server	decl-lsp: the server’s capabilities, one by one — diagnostics, hover, completion, navigation, hierarchies, rename, code actions, hints, lenses, semantic tokens, workspaces
04. Editor extensions	vscode-decl and zed-decl: the editor faces of the server and the REPL — VS Code’s language contribution, server management, live output preview, bound inputs, trace view, tasks, Test Explorer, and web extension; Zed’s grammar, queries, runnables, and server pointer; other editors
05. Renderer	@render, documents in YAML, --format / --indent, and the template dialect implemented three times: the form a module declares for its outputs, as tooling (delivered, Phase 10)
Development handbook	How the repository is set up and worked on: layout and configuration files, toolchains and versions, getting started, building and testing, quality tools, CI, releases, editors, conventions
Performance	What the implementations do to avoid work, current figures and remaining boundaries, how to measure, the Rust runtime representation and its opt-in diagnostics, the measured history through 2026-09-10, and the dated record of the investigation since (sections 1 to 49)
Reproducible performance comparisons	Frozen experiment manifests, output contracts, serial paired measurements, failure handling, and efficient iteration records

Models and examples

Document	Description
examples/	Service Graph and Hardware Interconnect evidence, runnable examples, comparison criteria, and the original desk-check findings