decl-lang
Decl is a declarative language for describing, generating, and validating structured data — a JSON superset with a strong static type system, constraints with first-class diagnostics, references, physical quantities, generics, and modules. Pure, deterministic, terminating.
This crate is the native Rust implementation of the whole language:
the tree-sitter grammar is compiled in, decl checks, evaluates,
validates, and formats modules (packages included), and decl-lsp is
the language server — no Node.js or wasm involved.
Command line
Diagnostics go to stderr as file: severity [code] id at path: message,
or into the JSON report with --json. The exit code is 1 when any error
was reported. An output declares the form it is emitted in with
@render({ format, indent, template, file, each }) — canonical or
indented JSON, YAML, or the text of a template in a small Jinja-like
dialect with Decl expressions inside, one file per element — and
--format, --indent, --template, --output override it
(docs/tooling/05_render.md in the repository).
Library
use ;
The functions are the decl command line in its own vocabulary:
inputs binds documents by input name (a JSON or YAML file, or JSON
text), outputs names the roots to return — outputs, or inputs bound
here or demanded through their fallback — and defaults to the entry
module's exported outputs; render returns each root's text in its
declared form (Rendered::Text, or Rendered::Files by path for a
fan-out root) with RenderOptions as the overrides, to_json and
to_yaml lay a document's text out; a failure is a DeclError whose
diagnostics carry the report. The npm package (evaluate, …) and the PyPI package
(decl.evaluate, …) offer the same functions with the same semantics;
the modules the functions are built from are public as well.
The high-level functions above and the CLI formats are the crate's contract.
The representation inside those modules is chosen for performance and changes
between releases without a migration path: the Engine's query graph is private
behind inspection methods, and slots, containers, paths and values share
storage behind copy-on-write accessors. Their contracts are in the API
documentation;
Rust runtime representation
says what code that uses them directly can rely on, and
Runtime diagnostics describes the
optional runtime-diagnostics Cargo feature.
Library layout
The crate is the same modules as the reference implementation, one
language rule in the same-named file everywhere (AGENTS.md in the
repository), and each is public:
| Module | Holds |
|---|---|
api |
the high-level API above: evaluate, render, check, validate, evaluate_source, format_source, to_json, to_yaml, DeclError, Diagnostic, Document, EvaluateOptions, RenderOptions, Rendered, TemplateSource, Report |
ast |
the syntax tree (specification chapter 11): declarations, types, members, expressions, source ranges |
parse |
the tree-sitter binding: parse_source, source text to ast |
semantics |
values, the environment (Env), resolved types (RT), diagnostics (Diag), canonical paths, the JSON reader and writers |
yaml |
documents in YAML: the YAML 1.2 core-schema reader into the JSON model, the block-style writer, the JSON layouts |
render |
the renderer: @render's form, the template dialect, the fan-out — one root to its text or files |
subsume |
the subsumption judgment ⊑ (§3.17) and structural emptiness (§3.19) |
infer |
expression inference and the static assignability of §4 |
checker |
the static checks of a module (check_module) |
engine |
binding, lazy evaluation, validation, serialization (Engine) |
pipeline |
one module end to end (run_pipeline, evaluate_source) |
module |
modules and the universe (load_modules, run_universe) |
package |
manifests, the resolver, the lock file (§8.6–8.7) |
fmt |
the canonical formatter (format) |
conformance |
the fixture corpus judge (judge_corpus) |
session |
the evaluation session behind the REPL and the server (Session) |
repl |
decl repl |
lsp |
decl-lsp |
cli |
decl |
Scope
The crate covers the whole language: parsing, the static checks of
chapters 3–4 (type resolution with generics and dimension algebra,
inference, assignability, the absence discipline, match
exhaustiveness), binding with lazy slots and cycle detection,
$referrers, assertions with diagnostic templates, canonical
serialization, modules and packages (decl.toml, decl.lock), the
canonical formatter, and the language server. Its output is
byte-identical to the reference implementation — the repository's
parity harness (tests/parity/differential.py, run by make verify)
diffs the Rust and Python runtimes against the reference over every
example and fixture that produces output.
Building from source
The grammar's C sources are compiled by build.rs. Inside the
repository they come from ../tree-sitter-decl/src; the published crate
carries a copy under grammar/ (generated by npm run build in
decl-ts/).
License
MIT — see LICENSE.