Decl Documentation

Status: v0.4 (2026-09-06) — 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), then v0.4: rendering is tooling, declared in the module with @render (D35; the E7xxx band, documents in YAML) — 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–D33, 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

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	Decl beside CUE, Pkl, jsonnet, Nickel, and JSON Schema: what each is for, a side-by-side table, where Decl differs, and when another tool is the better one
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

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

Validation cases (§0.5 desk-check artifacts)

Document	Description
examples/	The generality benchmark cases in the new syntax, with the desk-check findings they produced