AEON Language

How AEON works: vocabulary, grammar, meaning layers, and processing boundaries.

This is the how page.

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.

Document shape Processing model AES Processing walkthrough Language guide Type reference

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.

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.

Learn moreLearn less

Tagged tree values

Nodes carry tagged children and attributes. Empty-node shorthand <tag> is equivalent to <tag()>, and node children use indexed canonical paths rather than becoming top-level bindings.

Spec Value Types: Node Core Compliance: Node

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.

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

CanonicalStable equivalence, signatures, hashes, and deterministic comparison.

PrettifiedReadable source formatting for people and docs.

CompactSmaller 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: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 Open ecosystem

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: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.

DeclareThe header names aeon.gp.temporal.v1 so tools can see which ecosystem agreement the document is asking for.

PreserveThe parser preserves the datetime, attributes, source spans, and canonical path in the assignment stream.

TrustA consumer decides whether that convention identifier maps to a trusted implementation.

InterpretOnly 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 Try in playground

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.

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 Open value types

Use the focused pages when you need a narrower view.

Language Guide

Read the core authoring forms

Bindings, containers, references, nodes, modes, and common grammar shapes in a practical guide.

Open guide

Processing Walkthrough

Watch a document become trusted

Follow source text through assignment events, schema checks, meaning validation, canonical output, and Tonic materialization.

Open processing

Value Types

Understand special value features

Null reasons, NaN, Infinity, prose, encoded values, semantic comments, and zoned round-trip time.

Open value types

Type Reference

Look up every core value form

A concise reference list for syntax, accepted literal values, aliases, and reserved names.

Open reference

View as Markdown