---
title: "aontu documentation"
description: "What aontu is, how its documentation is organised, and a 30-second taste of unification."
source: "https://aontu.dev/docs/"
---

# aontu documentation

Rendered from [`docs/index.md`](https://github.com/aontu-lang/aontu/blob/main/docs/index.md) in the engine repository, where a correction belongs, and where the test suite executes every example on this page.

aontu is a JSON structure **unifier**: a small language (a purpose-specific dialect inspired by [CUE](https://cuelang.org/)) and an engine that merges partial structures into one consistent result, or reports exactly where they conflict. The same source can describe data, the schema that constrains it, and the defaults that fill it in: all in one notation, all combined by a single operation: _unification_.

This repository ships **two implementations kept in parity**:

-   **TypeScript** in [`ts/`](https://github.com/aontu-lang/aontu/blob/main/ts/): the canonical implementation, published to npm as [`aontu`](https://npmjs.com/package/aontu).
-   **Go** in [`go/`](https://github.com/aontu-lang/aontu/blob/main/go/): a port (`github.com/aontu-lang/aontu/go`) that mirrors the core semantics.

Both are checked against one language-agnostic test suite in [`test/spec/`](https://github.com/aontu-lang/aontu/blob/main/test/spec/), and every example in these pages is executed by that machinery too: the outputs come from the engine, not from the author’s memory.

## How this documentation is organised

The documentation is split by **what you are trying to do** when you open it. Reach for the part that matches your need:

| If you want to… | Read |
| --- | --- |
| **Learn** aontu from zero by building something, step by step | [Tutorials](https://aontu.dev/docs/tutorial) |
| **Accomplish a specific task** you already have in mind | [How-to guides](https://github.com/aontu-lang/aontu/blob/main/docs/how-to/) |
| **Look up** exact syntax, semantics, options, or API surface | [Language reference](https://aontu.dev/docs/reference-language) · [API reference](https://aontu.dev/docs/reference-api), with three supplements below |
| **Understand unification itself**: meet, top, bottom, the lattice | [Unification](https://aontu.dev/docs/unification) |
| **Understand** how and why the engine works the way it does | [Explanation](https://aontu.dev/docs/explanation) |
| **See whole systems defined**, each with its checks runnable | [Use cases](https://aontu.dev/docs/use-cases) |

There are four tutorials, each building one thing and showing the output of every step: a config that is schema, defaults, and data at once; the graph layer of identity, relations, and reachability; sharing a model as a versioned package; and computing source files from a model. The [index](https://aontu.dev/docs/tutorial) says what each one assumes.

The how-to guides are one page per task, grouped six ways: run, embed and integrate; templates, defaults and composition; schemas and constraints; query, explain and change; validate and evolve; modules and multi-file.

Three capabilities have doorways of their own:

-   **Declare and check relations.** Entities carry identity, the edges between them are declared in the model, and the engine checks both. The recipe is [check relations](https://aontu.dev/how-to/check-relations); the live version is [`use-cases/12-relations`](https://aontu.dev/use-cases/12-relations); the normative rules are under [Declared relations](https://aontu.dev/docs/reference-language#declared-relations).
-   **Write a recursive schema.** A schema can name itself, so trees and nested structures validate to any depth. The recipe is [define a recursive schema](https://aontu.dev/how-to/define-a-recursive-schema); the live version is [`use-cases/13-recursive-schema`](https://aontu.dev/use-cases/13-recursive-schema); the semantics are under [Recursive references](https://aontu.dev/docs/reference-language#recursive-references-fixpoints).
-   **Generate code from a model.** The field names, types and optionality a Go struct or a TypeScript interface needs are already in the model, and the unifier computes the file: a rule set over the records, `match` for the type mapping, a backtick string to carry the target text, and a component tree of files and lines that a generator runtime writes to disk and holds against its golden. The recipe is [generate code from a model](https://aontu.dev/how-to/generate-code); the live version, with three targets in one document and a check that both ports build identical trees, is [`use-cases/15-code-generation`](https://aontu.dev/use-cases/15-code-generation). The rules for the tree itself are the [Generation reference](https://aontu.dev/docs/reference-generation).

Six reference sections sit beside the two above. Each is a surface that cuts across the language reference rather than a part of it, which is what the language reference, organised by topic, cannot show at once:

-   [Generation reference](https://aontu.dev/docs/reference-generation). The component tree: every component node, the props it carries, the children it admits, and what `aontu render` and `aontu trace` do with a tree.
-   [Functions reference](https://aontu.dev/docs/reference-functions). The call surface of every built-in: arity, argument modes, accepted kinds and result words, as one table and as slices through it.
-   [Error reference](https://aontu.dev/docs/reference-errors). Every registered error code, by class, with what raises it and what a report carries.
-   [Packages reference](https://aontu.dev/docs/reference-packages). The files the package system keeps, every field `pkg.aontu` declares, the name rules, the caps, what an archive may hold, and every refusal code.
-   [Grammar reference](https://aontu.dev/docs/reference-grammar). The published grammar rule by rule, the spellings the parser accepts beyond it, and what holds the four grammar files to the engine.
-   [Agent and editor reference](https://aontu.dev/docs/reference-agents). Every door a machine comes in by, the one answer shape they share, what none of them does, and the posture each takes towards includes.

Tooling:

-   [The `aontu` command](https://aontu.dev/docs/reference-api#command-line-interface). One binary, nineteen verbs, both implementations. Each verb has its own reference section:

    -   validate: [`vet`](https://aontu.dev/docs/reference-api#aontu-vet), wrapped for CI as a [GitHub Action](https://github.com/aontu-lang/aontu/blob/main/vet-action/README.md)
    -   evolve a schema: [`subsume`](https://aontu.dev/docs/reference-api#aontu-subsume), [`breaking`](https://aontu.dev/docs/reference-api#aontu-breaking)
    -   ask and change: [`get`](https://aontu.dev/docs/reference-api#aontu-model-get), [`why`](https://aontu.dev/docs/reference-api#aontu-model-why), [`set`](https://aontu.dev/docs/reference-api#aontu-model-set), [`trim`](https://aontu.dev/docs/reference-api#aontu-trim)
    -   identity and relations: [`relations`](https://aontu.dev/docs/reference-api#aontu-relations), [`reaches`](https://aontu.dev/docs/reference-api#aontu-reaches), [`view`](https://aontu.dev/docs/reference-api#aontu-view)
    -   export and pin: [`jsonschema`](https://aontu.dev/docs/reference-api#aontu-jsonschema), [`hash`](https://aontu.dev/docs/reference-api#aontu-hash)
    -   generate: [`template`](https://aontu.dev/docs/reference-api#aontu-template), [`trace`](https://aontu.dev/docs/reference-api#aontu-trace) (the guide: [Generate code from a model](https://aontu.dev/how-to/generate-code))
    -   depend and publish: [`sync`](https://aontu.dev/docs/reference-api#aontu-sync), [`add`, `get`, `remove`](https://aontu.dev/docs/reference-api#aontu-add-aontu-get-aontu-remove), [`why`](https://aontu.dev/docs/reference-api#aontu-why), [`publish`](https://aontu.dev/docs/reference-api#aontu-publish), [`pkg`](https://aontu.dev/docs/reference-api#aontu-pkg)
    -   hand over: [`agentsmd`](https://aontu.dev/docs/reference-api#aontu-agentsmd)
    -   keep in the agreed form: [`fmt`](https://aontu.dev/docs/reference-api#aontu-fmt) (the form: [The formatted form](https://aontu.dev/docs/reference-language#the-formatted-form); the guide: [Format a document](https://aontu.dev/how-to/format-a-document))

    With no file at all, `aontu` starts a REPL.

-   [Language Server (LSP)](https://aontu.dev/docs/lsp). The `aontu-lsp` diagnostics server (TypeScript and Go), how to wire it into an editor, and the reusable LSP library API.

-   [The MCP server](https://aontu.dev/docs/reference-api#the-mcp-server). `aontu mcp`, a Model Context Protocol server over stdio, answering with the identical reports the CLI prints.

For agents:

-   [The aontu skill](https://github.com/aontu-lang/aontu/blob/main/docs/skill/SKILL.md). An agent-facing teaching pack: the [grammar card](https://github.com/aontu-lang/aontu/blob/main/docs/skill/grammar-card.md), a [worked example ladder](https://github.com/aontu-lang/aontu/blob/main/docs/skill/examples.md) whose documents the test suite executes, and the [error-code index](https://github.com/aontu-lang/aontu/blob/main/docs/skill/error-codes.md).
-   [The published grammar](https://aontu.dev/docs/reference-language#the-published-grammar): [`grammar/aontu.abnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.abnf) to read, with railroad diagrams; [`aontu.gbnf`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.gbnf) and [`aontu.lark`](https://github.com/aontu-lang/aontu/blob/main/grammar/aontu.lark) for constrained decoding.

Contract:

-   [The trust contract](https://aontu.dev/docs/trust). Hermeticity, termination, determinism, and sandboxing: what a host may rely on when evaluating an aontu document, and where each guarantee is conditional.

For contributors:

-   [The style guide](https://github.com/aontu-lang/aontu/blob/main/docs/STYLE-GUIDE.md). How these pages are written: Diátaxis placement, the voice, the banned-phrase list, and the snippet directives under which every example runs.

### Why the split?

The four kinds of document answer four different questions and are kept separate on purpose. A tutorial holds your hand and is allowed to omit detail; a how-to assumes you know the basics and just need the recipe; a reference is exhaustive and dry so you can trust it as the source of truth; an explanation is discursive and is the only place that argues about trade-offs. Mixing them (a reference that teaches, a tutorial that digresses into design rationale) serves none of those needs well, so each lives in its own file.

The rule applies to the toolkit as much as to the language, which is why a verb can appear in all four kinds without any of them repeating another: met once, in passing, while a tutorial builds something; given as a recipe for one goal in a how-to guide; specified exhaustively (every flag, every exit code) in the API reference; and argued for, never merely listed, in the explanation. The use cases stand alongside as whole worked systems, each holding a `check.sh` that CI runs.

## A 30-second taste

```aontu
# A schema, a default, and data — unified into one result.
port: *8080|integer
host: string
host: "localhost"
```

Unifying the three lines above yields:

```json
{ "host": "localhost", "port": 8080 }
```

The `port` is constrained to be an `integer`, defaults to `8080`, and, because nothing overrode the default, `8080` is what comes out. `host` is constrained to a `string` and pinned to `"localhost"`. Conflicting facts (a second `port: "high"`, say, or a `port: 1.5`) are refused with a precise error rather than silently resolved: the preferred branch keeps the kind it names, which is [argued in the explanation](https://aontu.dev/docs/explanation#a-preference-is-gated-by-kind-not-by-family).

Try it without writing a file: both implementations ship an `aontu` command that evaluates a file, reads stdin, or starts a REPL:

```sh
$ echo 'port: *8080 | integer' | aontu
{
  "port": 8080
}
```

Start with [build a config that checks itself](https://aontu.dev/docs/tutorial-config), the first of four [tutorials](https://aontu.dev/docs/tutorial).