<!-- AEON Language -->
# The ins and outs of vocabulary, grammar, meaning layers, and processing boundaries.
## How does AEON work?
This page explains the fundamental workings of the AEON language system: the visible syntax, the vocabulary AEON uses, the grammar shape, the layered processing model, and the philosophy that keeps meaning separate from authority.
Use this page when you already understand why AEON might matter and want to know how the language is built and interacts with its ecosystem.
[Document shape](#document-shape)
[Processing model](#processing)
[AES](#aes)
[Glossary](/glossary.php)
[Processing walkthrough](/walkthrough-processing.php)
[Language guide](/language.php)
[Type reference](/type-reference.php)
<!-- Document Shape -->
## AEON starts with explicit bindings.
A binding¹ connects a key to a value. A type annotation can make the intended value family visible. Attributes² can add local side information without changing the value itself.
```aeon
title:string = "Release notes"
count:number = 7_000
published:toggle = on
width@{unit:string = "cm"}:number = 33
```
Objects, lists, tuples, references, and nodes build on the same visible pattern³ rather than introducing a second hidden language.
<!-- Vocabulary -->
## The everyday words are deliberately small.
### Binding
- **Definition:** a key, optional attributes, optional datatype annotation, and assigned value.
### Value
- **Definition:** the bound data itself: a scalar, container, reference, node, prose block, encoded value, or special literal.
### Attribute
- **Definition:** structured metadata attached locally to a binding or anonymous value head.
### Reference
- **Definition:** a value that points at another path. Clone references use ~path; pointer references use ~>path.
### Node
- **Definition:** a tagged tree value for ordered, nested, document-like structures.
### Semantic comment
- **Definition:** a structured side-channel comment that can carry notes, annotations, guidance, or workflow context without becoming ordinary data.
<!-- Grammar -->
## The grammar is meant to keep the visible form predictable.
AEON is shaped around assignments, typed values, containers, references, and nodes. The grammar exists to preserve what was written and produce deterministic events, not to infer hidden meaning.
```
binding = key attributes? type? "=" value
typed value = ":" type "=" value
object = "{" bindings "}"
list = "[" values "]"
tuple = "(" values ")"
node = "<" name attributes? children? ">"
reference = "~" path | "~>" path
```
The full normative grammar belongs in the specs and CTS. This page is the readable map of the moving parts.
<!-- Orthogonal Composition -->
## The same grammar surfaces reappear in different contexts.
AEON is intentionally orthogonal: bindings, attributes, datatype claims, anonymous child heads, containers, nodes, and references compose through shared rules rather than separate mini-languages.
[Read orthogonal composition](/orthogonal-composition.php)
<!-- Processing -->
## AEON separates reading, validation, and materialization.
Many parsers effectively read text and produce application objects in one move. AEON splits that path so each stage has a narrow responsibility and the consumer can choose how much to accept for the current context.
```
bytes → tokens → AES → AEOS → meaning validation → Tonic → runtime
pre-parse → byte limits, encoding checks, size controls
lexer → syntax tokens, one pass, no backtracking traps
parser → structure and paths, no runtime objects
AES → ordered assignment events
AEOS → schema validation, no mutation or typecasting
meaning → consumer context, domain rules, and policy checks
Tonic → trusted materialization under consumer policy
```
Canonical form is not a required stop between meaning validation and materialization. It is a stable representation that can be produced from the accepted stream when a tool needs comparison, signing, hashing, or reproducible output.
<!-- AES -->
## The Assignment Event Stream is the handoff point between tools.
AEON Core⁴ reads source text and emits AES⁵: ordered assignment events with paths, source order, datatype hints, attributes, references, and structure. That stream is the stable layer other processors consume.
```
source text → lexer → parser → AES
AES → AEOS validation
AES → meaning validation
AES → Tonic materialization
AES → canonical representation
AES → prettified AEON source
AES → compact/minified AEON source
```
- **Canonical** Stable equivalence, signatures, hashes, and deterministic comparison.
- **Prettified** Readable source formatting for people and docs.
- **Compact** Smaller transport while preserving the same accepted structure.
Those are projections from the event stream, not different interpretations of the document.
<!-- Annotation Stream -->
## Comments and semantic notes travel beside the assignment stream.
AEON can preserve semantic comments as an annotation stream instead of discarding them or turning them into ordinary data. This gives tools a place for documentation, workflow hints, rendering notes, or domain-specific side languages.
```
source text → AES
↘ annotation stream
AES → data, structure, paths, attributes
annotation stream → comments, semantic notes, tooling hints
```
A consumer that only needs data can ignore the annotation stream. A trusted tool that understands a comment language can opt into it without forcing every AEON processor to execute or interpret that language.
<!-- Meaning Layers -->
## Profiles, schemas, conventions, and Tonics add meaning without blurring authority.
AEON Core preserves structure and claims. Profiles⁶ name optional semantic behavior. Schemas⁷ validate shape. Conventions⁸ define ecosystem agreements. Meaning validation applies consumer context. Tonics⁹ materialize domain objects after the consumer has chosen what to trust.
```aeon
aeon:profile = "example.content.v1"
aeon:schema = "example.content.schema.v1"
document:object = {
title:string = "Release notes"
status:toggle = on
}
// The document declares claims.
// The consumer chooses which layers to trust.
```
[Open schemas](/schemas.php)
[Open ecosystem](/ecosystem.php)
<!-- Convention Example -->
## A convention is implemented as ordinary AEON metadata plus a trusted consumer rule.
Temporal data shows the pattern clearly. AEON Core can parse a datetime literal without deciding how every application should handle time zones, daylight-saving ambiguity, calendars, or timezone database drift.
```aeon
aeon:header = {
conventions = [
"aeon.gp.temporal.v1"
]
}
meeting@{
target:string = "zone"
zone:string = "Australia/Melbourne"
calendar:string = "iso8601"
tzdbVersion:string = "2026b"
disambiguation:string = "reject"
}:datetime = 2026-06-06T10:10:00
```
To AEON Core, this is still a binding named meeting with a datetime value and an attribute object. The convention does not add grammar, execute code, or force a runtime object into existence.
- **Declare** The header names aeon.gp.temporal.v1 so tools can see which ecosystem agreement the document is asking for.
- **Preserve** The parser preserves the datetime, attributes, source spans, and canonical path in the assignment stream.
- **Trust** A consumer decides whether that convention identifier maps to a trusted implementation.
- **Interpret** Only after that choice does a Tonic or profile-aware tool apply zone, calendar, tzdbVersion, and disambiguation behavior.
That is how conventions stay powerful without becoming hidden parser behavior: the document can make the claim, but the consumer owns adoption.
[See contracts](/ecosystem.php#contracts)
[Try in playground](/playground.php)
<!-- Philosophy -->
## The parser preserves claims; it does not decide their domain truth.
A value can be syntactically valid, structurally valid, and still fail domain meaning. AEON keeps that distinction visible so a consumer can validate before materializing runtime meaning.
```aeon
temperature:number = 0 // celsius, fahrenheit ?
---
temperature@{unit:string = "celsius"}:number = 0
---
temperature@{unit:string = "fahrenheit"}:number = 32
```
That is the language's deeper stance: keep meaning visible, keep trust explicit, and let each layer prove one thing and nothing more.
[Read philosophy](/philosophy.php)
[Open value types](/value-types.php)
<!-- Next -->
## Use the focused pages when you need a narrower view.
### Read the core authoring forms
_Language Guide_
Bindings, containers, references, nodes, modes, and common grammar shapes in a practical guide.
[Open guide](/language.php)
### Watch a document become trusted
_Processing Walkthrough_
Follow source text through assignment events, schema checks, meaning validation, canonical output, and Tonic materialization.
[Open processing](/walkthrough-processing.php)
### Understand special value features
_Value Types_
Null reasons, NaN, Infinity, prose, encoded values, semantic comments, and zoned round-trip time.
[Open value types](/value-types.php)
### Look up every core value form
_Type Reference_
A concise reference list for syntax, accepted literal values, aliases, and reserved names.
[Open reference](/type-reference.php)
## Definitions
¹ **Binding:** an assignment from an identity to a value, with optional attributes and type labels. At the surface it can look like key plus value; semantically it carries identity plus claims.
² **Attribute:** structured local metadata attached to a binding, anonymous value, or node. Attributes carry side information without changing the value itself.
³ **visible pattern:** a repeated grammar shape that stays inspectable across contexts
⁴ **AEON Core:** the core language and parser layer responsible for recognizing AEON syntax and preserving structure as assignment events, without deciding domain meaning.
⁵ **AES:** Assignment Event Stream. The ordered preservation artifact produced from AEON source, used by later validation, canonicalization, auditing, and materialization steps.
⁶ **Profile:** a named processing or interpretation context that narrows which features, schemas, conventions, or materialization behavior a consumer accepts.
⁷ **Schema:** a validation document or rule set that checks form: existence, required fields, declared types, shape, and structural constraints.
⁸ **Convention:** a documented meaning pattern layered on top of AEON Core. Conventions let communities share intent without making that intent an implicit parser rule.
⁹ **Tonic:** a trusted materializer or consumer-side adapter that turns accepted AEON meaning into a runtime object, rendered document, API payload, or other projection.