# aontu

> aontu is a language for the ontology of a software system: the entities it contains, the types they must have, and the relations that must hold between them. The definition is machine-checkable, so a change proposed by a coding agent is admitted or refused with the offending line named.

Documented against `aontu` 0.73.0. Every page below is also
served as markdown: append `.md`, or send `Accept: text/markdown` to the
page's own URL.

## When to use aontu

aontu is a library and a CLI you run yourself, not a hosted service. It is
a language for the **ontology of a system**: the entities it contains, the
types they must satisfy, and the relations that must hold between them.
Reach for it when **a rule spans more than one file, service or team, and
being wrong silently is expensive**: the rules a type checker inside one
service cannot see, and prose in a README cannot enforce.

For an agent this is the referee: propose a change, run `vet`, and get a
verdict with an exit class and an error code rather than an opinion. Every
refusal names the file, line and column that caused it.

Good fits:

- A checkable definition of a system an agent is editing: which services
  exist, who owns them, which may call which, what a record must carry.
- Rules that live between entities rather than inside one: typed
  references, an acyclic dependency graph, an inverse edge that must be
  written back. `rel()`, `acyclic()` and `inverse()` state them; the
  engine refuses the document when they do not hold.
- Layered configuration (base, environment, region, instance), where a
  plain deep merge already gives order-dependent answers.
- Validating that a concrete document satisfies a schema *and* returning
  the filled-in result, rather than only a pass or fail.
- Checking that two specifications are mutually consistent before either
  is deployed, and naming the exact path that conflicts when they are not.
- Constraining what a model may emit: the grammar below is GBNF, so a
  sampler can be held to syntactically valid aontu.

Poor fits, where something simpler wins:

- One flat config file with no layering: parse the JSON and move on.
- Merges where last-write-wins is genuinely what you want.
- Program logic: there are no user-defined functions, no loops and no I/O,
  deliberately. Evaluation terminates and is deterministic, which is what
  makes the verdict trustworthy; it is not what makes it expressive.
- Hot paths: this is a build- and load-time tool, not a per-request one.

How to run it:

- CLI: `npm install -g aontu@0.73.0` then `aontu file.aontu`.
- MCP: `npx -p aontu@0.73.0 aontu mcp`, a local stdio server
  exposing the engine as tools, answering with the same reports the CLI
  prints. It runs on your machine; there is no hosted endpoint, because
  resolving a document does not need one.
- Library: `npm install aontu@0.73.0`, or the Go module.
- In the browser, with nothing installed: [the playground](https://aontu.dev/playground).

## Documentation

- [aontu documentation](https://aontu.dev/docs.md): What aontu is, how its documentation is organised, and a 30-second taste of unification.
- [Tutorials](https://aontu.dev/docs/tutorial.md): The four tutorials, what each one builds, and which to read first.
- [Tutorial: build a config that checks itself](https://aontu.dev/docs/tutorial-config.md): Learn aontu from zero by building a config that checks itself, step by step.
- [Tutorial: model the system, not the tree](https://aontu.dev/docs/tutorial-graph.md): Model a system with identities, declared relations, and recursive schemas.
- [Tutorial: share a model as a package](https://aontu.dev/docs/tutorial-package.md): Publish a schema as a package, acquire it from another project, and watch the pin refuse a change to what it means.
- [Tutorial: from a model to a file tree](https://aontu.dev/docs/tutorial-generate.md): Compute a TypeScript client from a model of its routes, then write the file tree with aontu render.
- [Language reference](https://aontu.dev/docs/reference-language.md): The core language, exhaustively: syntax, semantics, the unification lattice, and every operator.
- [Generation reference](https://aontu.dev/docs/reference-generation.md): The component tree: every component node, its props and the children it admits, and what aontu render and aontu trace do with it.
- [Functions reference](https://aontu.dev/docs/reference-functions.md): The call surface of all 64 built-ins: arity, argument modes, accepted kinds and result words, as one table and as slices through it.
- [Errors reference](https://aontu.dev/docs/reference-errors.md): Every registered error code, by class, with what raises it, how a report is shaped, and which exit code a verb answers with.
- [Packages reference](https://aontu.dev/docs/reference-packages.md): The package system's artefacts: the files it keeps, every field pkg.aontu declares, the name rules, the caps, the archive allowlist, and every refusal code.
- [Grammar reference](https://aontu.dev/docs/reference-grammar.md): The published grammar rule by rule, the spellings the parser accepts beyond it, and the checks that hold the four grammar files to the engine.
- [Agent and editor reference](https://aontu.dev/docs/reference-agents.md): Every door a machine reads a model through, the one answer shape they share, what none of them does, and the include posture each takes.
- [API reference](https://aontu.dev/docs/reference-api.md): The API and the command line: every verb, every flag, every exit code, and the MCP server.
- [aontu Language Server (LSP)](https://aontu.dev/docs/lsp.md): The aontu-lsp language server: diagnostics, hover and completion, how to wire it into an editor, and the reusable library API.
- [Use cases](https://aontu.dev/docs/use-cases.md): The executed, enterprise-shaped models: the evidence the documentation's examples are lifted from.
- [Unification](https://aontu.dev/docs/unification.md): The one operation, and the vocabulary for it: meet, top, bottom, the lattice, and the three laws that make order irrelevant.
- [Explanation: how and why aontu works](https://aontu.dev/docs/explanation.md): How and why the engine works the way it does: the only part of the documentation that argues about trade-offs.
- [The aontu trust contract](https://aontu.dev/docs/trust.md): The trust contract: hermeticity, termination, determinism and sandboxing: what a host may rely on, and where each guarantee is conditional.

## How-to guides

- [Run a file or start a REPL](https://aontu.dev/how-to/run-cli-and-repl.md): Evaluate a file, read from stdin, or question a document interactively with the `aontu` command.
- [Call aontu from TypeScript](https://aontu.dev/how-to/call-from-typescript.md): Embed the engine in Node with the `Aontu` class: parse, unify and generate from your own code.
- [Call aontu from Go](https://aontu.dev/how-to/call-from-go.md): Embed the engine with the Go port: the same three calls, with errors returned instead of thrown.
- [See the canonical form](https://aontu.dev/how-to/see-canonical-form.md): Print what a document means (defaults, disjunctions and all) instead of what it resolves to.
- [Inject values from the host program](https://aontu.dev/how-to/inject-host-values.md): Fill `$name` variables from the calling program to parameterise a model from code.
- [Give an agent an entrypoint to a definition](https://aontu.dev/how-to/give-an-agent-an-entrypoint.md): Generate a ground-truth stanza with `aontu agentsmd` and serve the verbs over MCP with `aontu mcp`.
- [Collect errors instead of throwing](https://aontu.dev/how-to/collect-errors.md): Gather every problem in one pass with `collect: true` (TypeScript) or `Check` (Go) instead of stopping at the first.
- [Read a conflict error](https://aontu.dev/how-to/read-a-conflict-error.md): What a conflict message names, in what order, and how to tell a conflict from an unresolved path.
- [Wire your editor](https://aontu.dev/how-to/wire-your-editor.md): Connect `aontu lsp` to VS Code, Neovim, or any LSP client for diagnostics as you type.
- [Provide defaults that callers can override](https://aontu.dev/how-to/provide-defaults.md): Write a default in a disjunction with the type an override must satisfy, and layer defaults by rank.
- [Apply a template to many keys](https://aontu.dev/how-to/apply-a-template-to-many-keys.md): Use a `&:` spread entry to unify one template into every key of a map or every element of a list.
- [Seal generated children deeply](https://aontu.dev/how-to/seal-generated-children.md): Close both the set of `pack`-generated children and each child's shape, or seal from the side with a hidden guard.
- [Reference and reshape other parts of the document](https://aontu.dev/how-to/reference-and-reshape.md): Pull other parts of the document in by reference, extend them, and relocate them with `move` and `copy`.
- [Keep schema and helper fields out of the output](https://aontu.dev/how-to/keep-schema-out-of-output.md): Mark schema and helper fields with `type()` or `hide()` so they constrain and compute without being generated.
- [Constrain every element of a list](https://aontu.dev/how-to/constrain-list-elements.md): Type every element of a list with a `&:` spread, and know why a bare `[string]` does not.
- [Forbid unexpected keys](https://aontu.dev/how-to/forbid-unexpected-keys.md): Seal a map with `close` so a typo'd or invented key is refused instead of absorbed.
- [Make a field optional](https://aontu.dev/how-to/make-a-field-optional.md): Suffix a key with `?` so a field that never receives a value is dropped instead of erroring.
- [Name a reusable constraint](https://aontu.dev/how-to/name-a-reusable-constraint.md): Build a `uint8`/`port` vocabulary as a `type()`-marked block of ordinary fields.
- [Define a recursive schema](https://aontu.dev/how-to/define-a-recursive-schema.md): Reference a definition inside itself to get a schema that applies at every depth of the data.
- [Carry exact money over JSON](https://aontu.dev/how-to/carry-exact-money-over-json.md): Keep money exact inside aontu and cross JSON as a fixed-scale decimal string with a conversion mark.
- [Export JSON Schema](https://aontu.dev/how-to/export-json-schema.md): Export a model as JSON Schema 2020-12 with `aontu jsonschema`, and read the loss report it owes you.
- [Generate code from a model](https://aontu.dev/how-to/generate-code.md): Generate target-language source from a model: a rule set over the records, a component tree of files and lines, and `aontu render` to write the bytes and hold them against their goldens.
- [Query a path](https://aontu.dev/how-to/query-a-path.md): Print one node of the evaluated document by path, or a keys, types, or depth-limited view of it.
- [Explain a value](https://aontu.dev/how-to/explain-a-value.md): List every contribution that met at a path (which file, which line, which layer) with aontu model why.
- [Change a value with an overlay](https://aontu.dev/how-to/change-a-value-with-an-overlay.md): Append a change to an overlay file with aontu model set, so the original document keeps its bytes and a bad change is refused before it lands.
- [Gate an agent's changes by role](https://aontu.dev/how-to/gate-changes-by-role.md): Ask aontu allow whether a role may change a subtree before aontu model set writes it, with the answer read from a role model that is itself an aontu document.
- [Change a pinned value](https://aontu.dev/how-to/change-a-pinned-value.md): Rewrite a pinned literal where the author wrote it with aontu model set --in-place, and know the cases where the verb appends instead.
- [Find dead entries](https://aontu.dev/how-to/find-dead-entries.md): Report map entries whose removal changes nothing, so layered files do not silt up with lines a template already implies.
- [Draw a model](https://aontu.dev/how-to/draw-a-model.md): Draw a model as a dependency tree, matrix or architecture layers with aontu view, and gate the committed figures in CI.
- [Validate data in CI](https://aontu.dev/how-to/validate-in-ci.md): Run aontu vet in a pipeline so a document that does not hold fails the build, with the reason attached.
- [Gate schema changes](https://aontu.dev/how-to/gate-schema-changes.md): Gate schema edits with aontu breaking, so a change that would refuse previously valid documents fails the review.
- [Check that components agree about their relations](https://aontu.dev/how-to/check-relations.md): Declare a relation once at the field with rel(), acyclic() and inverse(), and have the whole model's edge set checked.
- [Query reachability between entities](https://aontu.dev/how-to/query-reachability.md): Ask whether one entity reaches another over the declared edges with aontu reaches, and get the path as the answer.
- [Pin what a document means](https://aontu.dev/how-to/pin-a-document-hash.md): Pin a document's meaning to one string with aontu hash, and detect when the meaning moves.
- [Format a document](https://aontu.dev/how-to/format-a-document.md): Put a document in the agreed form with `aontu fmt`, gate a repository on it in CI, read what the formatter will and will not change, and point `--lint` at the style it never touches.
- [Split a model across files](https://aontu.dev/how-to/split-a-model-across-files.md): Load other source files with @"path" so a base model and its overrides unify into one document.
- [Vendor a dependency closure for an offline build](https://aontu.dev/how-to/vendor-a-dependency-closure.md): Lock a dependency closure with aontu sync and commit aontu_meta/vendor/ so a build resolves every import with no network at all.
- [Vendor a module by hand](https://aontu.dev/how-to/vendor-by-hand.md): Bootstrap a module dependency with no repository to fetch from by copying its source tree into aontu_meta/vendor/ and letting aontu sync pin what it means.
- [Publish a package](https://aontu.dev/how-to/publish-a-package.md): Publish a package with aontu publish, gated on compatibility with the version before it, into a local repository that aontu pkg serve serves and aontu sync reads.

## Use cases

Enterprise-shaped systems built as real aontu documents and executed
against the CLI by a `check.sh` that asserts every outcome. Long-form
records rather than reference material, so they are indexed here and
NOT concatenated into /llms-full.txt. Fetch the ones you need.

- [01. A company-wide service catalog as system ontology](https://aontu.dev/use-cases/01-service-catalog.md): Company-wide service catalog as system ontology (two views of the same entities). Exercises `refer()` over tree paths, `relations` (acyclic + inverse), `@"aontu:system"`, `get`/`why`, vet-gated onboarding.
- [02. Multi-environment deployment configuration](https://aontu.dev/use-cases/02-deploy-config.md): Multi-environment deployment config: org → team → service → env layering. Exercises ranked `*`/`**` defaults, includes, `close()`, constraint atoms, `pack`, `filter`, `why`.
- [03. A REST API contract as agent ground truth](https://aontu.dev/use-cases/03-api-contract.md): REST API contract as the truth an agent codes against; emit→validate→repair. Exercises `vet` (json/sarif/exit classes), `--at`, `--closed`, repair from vet's findings.
- [04. Schema-evolution governance for a shared customer-profile schema](https://aontu.dev/use-cases/04-schema-evolution.md): Governance of a shared schema across v1→v3. Exercises `subsume` profiles, `breaking --against`, `deprecate()`, `aontu_policy.compat`, `hash`, `diff`.
- [05. RBAC / authorization policy as ground truth](https://aontu.dev/use-cases/05-rbac-policy.md): RBAC / authorization model as data. Exercises `close()` exhaustiveness, disjunct shapes, `match`, `filter`+`length` invariants, `must()`.
- [06. Kubernetes golden path: one service model, N manifests](https://aontu.dev/use-cases/06-k8s-golden-path.md): Platform golden path generating k8s-shaped manifests for N services. Exercises `pack`/`each`, `key()`, `_`, `unique()`, overrides onto generated children.
- [07. Event/message contracts (the schema-registry case)](https://aontu.dev/use-cases/07-event-contracts.md): Event/message contracts (schema-registry case). Exercises envelope spreads, discriminated unions, `re()` formats, `0d` ids, `breaking`.
- [08. Feature flags / runtime config (the write-path case)](https://aontu.dev/use-cases/08-feature-flags.md): Feature flags with env/tenant overrides and an operational write path. Exercises `set` (overlay + `--in-place`), pinned-value refusals, ranked defaults, `--trust` confinement.
- [09. An AI agent platform's tool registry as ground truth](https://aontu.dev/use-cases/09-agent-tools.md): An agent platform's tool registry; runtime call guardrail; the MCP server itself. Exercises per-tool `vet --at`, the real `aontu-mcp` over JSON-RPC, `agentsmd`, generation.
- [10. Enterprise data domain model (customers, orders, invoices, money)](https://aontu.dev/use-cases/10-data-model.md): Enterprise data domain with exact money and 64-bit ids. Exercises `0d` exact leaves, `lossy_integer_literal`, cross-field constraints, batch `vet`, `subsume`, the schema rendered as TypeScript and Go.
- [11. Shared truth across repos: distributing a schema package](https://aontu.dev/use-cases/11-shared-modules.md): Shared truth across repos: a schema package published, served and synced into a consumer. Exercises `publish`/`sync`/`get`/`why`, `pkg tidy`/`verify`/`serve`, three lockfile pins, integrity errors, `#aon1-…` inline pins.
- [12. Relations: a pipeline DAG, declared once, enforced at generation](https://aontu.dev/use-cases/12-relations.md): Pipeline DAG: field-declared relations, one line of schema. Exercises `rel(t)`, held constraints, `acyclic()`/`inverse(n)` atoms, verdict at generation, `relations`/`reaches`.
- [13. Recursive schema: an approval chain, one reference deep, any data deep](https://aontu.dev/use-cases/13-recursive-schema.md): Approval chain: a schema one reference deep over any-depth data. Exercises recursive residuals (`$.spec.Step`), mu-form canon + hash, `recursion_unexpanded`, `vet --at` over plain JSON.
- [14. JSON Schema export: the bridge out, and the loss report](https://aontu.dev/use-cases/14-jsonschema-export.md): JSON Schema as the bridge out: MCP inputSchema, OpenAPI, stock validators. Exercises `jsonschema --at`/`--strict`/`--format json`, the stderr loss report, exit classes, the money-wire `const` mark.
- [15. Code generation](https://aontu.dev/use-cases/15-code-generation.md): The model as the source of the code: Go, TypeScript and SQL from one catalogue, each over a slice. Exercises list-spread + `pick` line building, `join` file assembly, backtick target text, `match` type mapping, both-ports byte parity.
- [16. Module deps: a layered codebase, drawn as a dependency tree](https://aontu.dev/use-cases/16-module-deps.md): A codebase's own module graph: four layers, no upward dependencies, drawn as a dependency tree and as the architecture layers. Exercises `rel(t)` target-shape flow as an architecture rule, `acyclic()`/`inverse(n)`, `reaches`, the tree, matrix and layer views.
- [17. Lambda handlers from a service model](https://aontu.dev/use-cases/17-lambda-handlers.md): Twelve Lambda handlers and their index from one service model, by a rule set written twice: as canonical aontu, and as a Lambda handler with its aontu on marked lines. Exercises `replace` with no hole syntax, `esc: sq`, verbatim whitespace, the empty-selection conditional, `each` order and the split-form-join chain, the template surface and its round trip, both-ports byte parity.
- [18. Role permissions for agent edits](https://aontu.dev/use-cases/18-role-permissions.md): Role permissions for agent edits: which role may change which subtree, asked before the change. Exercises `allow` (the deciding entry named as a path into the role model, `--at`, `--format json`, exit classes), a `close()`d role vocabulary, the allow-then-`set` loop, an agent skill, `why` on the rule.

## Examples

Whole applications generated from one aontu model and held to an
external validation: the reference implementation's own test script,
run over HTTP against the generated app. Records rather than reference
material, so they are indexed here and NOT concatenated into
/llms-full.txt.

- [rb-solar: a Rails application, generated](https://aontu.dev/examples/rb-solar.md): Ruby on Rails 8, SQLite, Hotwire: the Solar System API (Planet, Moon) and a human UI over the same data. Held to voxgig-sdk/voxgig-solardemo-sdk, which supplies the OpenAPI description, the validation script and the Ruby SDK. nine checks, including the reference's own twenty tests.
- [Read the Rails application model](https://aontu.dev/examples/rb-solar/model.md): Inspect the Rails model: field properties, parent associations, entity order, and prepared seed rows.. Held to voxgig-sdk/voxgig-solardemo-sdk, which supplies the OpenAPI description, the validation script and the Ruby SDK. nine checks, including the reference's own twenty tests.
- [Generate Rails code with aontu templates](https://aontu.dev/examples/rb-solar/rails-code.md): Follow a component tree, template markers, emit rules, and replacements from the model to Rails source files.. Held to voxgig-sdk/voxgig-solardemo-sdk, which supplies the OpenAPI description, the validation script and the Ruby SDK. nine checks, including the reference's own twenty tests.
- [Generate the entity relationship diagram](https://aontu.dev/examples/rb-solar/erd.md): Generate Mermaid text from entity definitions, understand cardinality rules, and check diagram drift.. Held to voxgig-sdk/voxgig-solardemo-sdk, which supplies the OpenAPI description, the validation script and the Ruby SDK. nine checks, including the reference's own twenty tests.
- [Change and check the generated Rails app](https://aontu.dev/examples/rb-solar/change-and-check.md): Add an optional field, regenerate Rails code and diagrams, and check the resulting application.. Held to voxgig-sdk/voxgig-solardemo-sdk, which supplies the OpenAPI description, the validation script and the Ruby SDK. nine checks, including the reference's own twenty tests.

## Beyond this site

- [Source](https://github.com/aontu-lang/aontu): both implementations, the shared test suite, and the design record.
- [Agent skill](https://github.com/aontu-lang/aontu/blob/main/docs/skill/SKILL.md): the teaching pack, with a grammar card, a worked example ladder and an error-code index.
- [Published grammar](https://github.com/aontu-lang/aontu/tree/main/grammar): GBNF and Lark, for constrained decoding.
- MCP: `npx -p aontu@0.73.0 aontu mcp`, a local stdio server answering with the same reports the CLI prints.
- [npm package](https://www.npmjs.com/package/aontu): the CLI, the language server and the MCP server all ship in it.

## Machine-readable surfaces

- [https://aontu.dev/openapi.json](https://aontu.dev/openapi.json): this site's content API in OpenAPI 3.1. Every operation has an operationId, a description and a typed response schema.
- [https://aontu.dev/errors.json](https://aontu.dev/errors.json): every error code the engine can raise, with the class that says what to do about it.
- [https://aontu.dev/grammar/aontu.abnf](https://aontu.dev/grammar/aontu.abnf): the grammar in ABNF (RFC 5234), the form to read; the language reference draws its railroad diagrams from this file.
- [https://aontu.dev/grammar/aontu.gbnf](https://aontu.dev/grammar/aontu.gbnf): the grammar in GBNF, for constrained decoding with llama.cpp and compatible samplers.
- [https://aontu.dev/grammar/aontu.lark](https://aontu.dev/grammar/aontu.lark): the same grammar in Lark, for parsing in Python.
- [https://aontu.dev/grammar/aontu.tmLanguage.json](https://aontu.dev/grammar/aontu.tmLanguage.json): the same grammar as a TextMate bundle, for syntax highlighting in an editor or a renderer.
- [https://aontu.dev/versions.json](https://aontu.dev/versions.json): the engine version this site runs, and the size of each surface.
- [https://aontu.dev/llms-full.txt](https://aontu.dev/llms-full.txt): the documentation and how-to sections above, concatenated, for one-request ingestion.
- [https://aontu.dev/sitemap-index.xml](https://aontu.dev/sitemap-index.xml): every URL on the site.
- Any page also answers `Accept: text/markdown` at its own URL, and errors
  come back as JSON under `Accept: application/json` with a stable `code`,
  a `hint`, and the site's entry points. All of these answer cross-origin.

## About this project

- [https://aontu.dev/about.md](https://aontu.dev/about.md): what aontu is, who maintains it, and how it is tested.
- [https://aontu.dev/contact.md](https://aontu.dev/contact.md): how to report a bug, a security issue, or a documentation error.
- [https://aontu.dev/privacy.md](https://aontu.dev/privacy.md): what this site collects: no cookies and no personal data, with optional cookieless aggregate analytics; the playground resolves entirely in your browser and sends nothing.