Skip to main content
Executable System Specification | ESSModel system intent as validated typed data, then derive deterministic artifacts and conformance checks from it.ESSreferenceessreferenceadopterdevelopertry-spec-driven-developmentspecify

Executable System Specification

ESS is a standalone Rust toolchain for describing systems as typed, validated data. A specification can be compiled into deterministic intermediate representation, inspected as a graph, compared semantically across revisions, projected into supported concrete formats, and used to generate the conformance scenarios an implementation must satisfy.

The command is ess. Its first level is four areas:

$ ess specify validate --path spec                                      # is the specification consistent?
$ ess generate --path spec --kind openapi --out generated               # derive a contract from it
$ ess verify conform synthesize --path spec --target typescript --out conformance   # the tests it obliges
$ ess infra import openapi --path api.yaml --out interface.json         # read an existing source

What ESS owns​

  • typed system, domain, entity, command, event, view, component, binding, and topology semantics;
  • deterministic compilation, inspection, graphing, semantic diff, and impact analysis;
  • documentation generation, as Markdown (docs) or as a browsable HTML site (site), and JSON Schema, OpenAPI, and AsyncAPI generation;
  • synthesis of what the specification determines, with explicit implementation obligations for the rest;
  • conformance-suite generation, runners in Go and TypeScript, and standalone reports;
  • OpenAPI and Kubernetes adapters with declared coverage;
  • sanitized infrastructure observation, analysis, simulation, drift, and projection.

What it refuses to claim​

An importer never fills a semantic gap by guessing. A projector never applies infrastructure or mutates a live system. Unsupported constructs remain visible as coverage gaps, unresolved references, obligations, or refusals. Round-trip guarantees apply only to the subset an adapter declares.

ESS generates documentation from a typed specification. It does not turn prose or Markdown into a specification, and it does not host the site it renders.

Where to go next​

You want toRead
Install ess, pin it for a project, and get from an empty directory to a passing conformance runGetting started
Understand what a specification declares and what is derived from itThe model
Adopt ESS without generating your code, or decide how far to goAdopt ESS at the depth you need
See one command's source next to every contract generated from itThe billing example
Look up a command, a format version or a predicateCLI, format versions, predicates
Know what is supported today and what is notWhere this stands