Home

AEON

A human-readable, typed, semantics-first data notation.

AEON is designed for documents that need more structure and meaning than plain JSON or YAML, while still staying readable and writable by people. It sits somewhere between JSON and XML: structured data front and center, with clear separation of concerns.

app:object = {
  name:string = "Hello World"
  version:number = 1
  active:toggle = on
  tags:list = ["demo", "wiki"]
}

Design principles

• Explicit datatypes — typed modes make datatype claims visible
• No implicit coercion — the parser never guesses
• Deterministic parsing — same input, same output, always
• Layered processing — structure, validation, and meaning are separate concerns

---

Start Here

New to AEON? Read these in order:

1. Introduction — Learn AEON in 5 minutes: syntax, types, values, references, modes
2. Key Features — The high-level map of what AEON provides as a system
3. Structure & Syntax — Bindings, attributes, anonymous child heads, separators, layout rules
4. Value Types — Scalar, container, trimtick, null, reference, and node families
5. Quick Start — Install a library, parse your first .aeon file (TypeScript, Rust, Python)
6. Examples — Real-world AEON documents: config files, signed envelopes, data interchange

Published Packages

The TypeScript implementation is now published on npm under the @altopelago scope. For application integrations, start with the runtime package:

npm install --ignore-scripts @altopelago/aeon-runtime@0.16.0

Lower-level packages are available for focused parser, AES, AEOS, canonical, CLI, and WebAssembly use cases.

Rust and native Python are also published at 0.16.0:

cargo add altopelago-aeon@0.16.0
# In a CPython 3.12–3.14 virtual environment:
python -m pip install altopelago-aeon==0.16.0

Python applications import altopelago.aeon, not the separate pure-Python reference package. See Quick Start for executable examples. The 0.16.0 migration guide covers reference-safe canonical ordering, type-only generic arguments and exact numeric clarifiers. Historical integrity verification bytes are unchanged. Consumers of the TypeScript SANSA namespace adapter should read the 0.15.0 migration guide. Those adapter changes were introduced in 0.15.0 and remain in 0.16.0; the language line is AEON v1.

Package changes are tracked in the implementation changelog.

Authority and Implementation Surfaces

• Implementation website: aeon.altopelago.com
• Specification website: aeonite.org
• Implementation repository: AltoPelago/aeon
• Specification repository: aeonite-org/aeonite-specs
• Conformance repository: aeonite-org/aeonite-cts

AltoPelago owns the maintained implementation surface. Aeonite publishes the specification and CTS surfaces this implementation follows.

Common Reader Paths

I want to write AEON documents

• Introduction
• Structure & Syntax
• Value Types
• Examples

I want to validate documents

• AEOS Schema Validation
• Contracts & Profiles
• Conformance & CTS

I want deterministic output, hashes, or signatures

• Canonical Form
• Security Conventions
• Security Model
• Operational Security Knobs

I want to implement AEON tooling

• Processing Model
• System Architecture
• Spec Reference

Language Guide

• Addressing & References — Canonical paths, clone vs pointer references, legality rules
• Comments & Annotations — Plain comments, structured channels, attachment behaviour
• Canonical Form — Deterministic rendering for hashing, signing, and diffing
• Key Features — Determinism, typed transport, validation layers, annotations, canonical form, and security-oriented design

Validation, Trust, and Conformance

• AEOS Schema Validation — Writing schemas, constraints, result envelopes, diagnostic codes
• Contracts & Profiles — Contract identifiers, profile declarations, trusted registries
• Security Conventions — Integrity, signatures, encryption: the GP security envelope
• Operational Security Knobs — Input limits, parser depth limits, pattern profile, references, and materialization budgets
• Conformance & CTS — Validating an implementation against the conformance test suites

Architecture and Design Notes

• Processing Model — What each phase emits, consumes, and guarantees
• Security Model — Zero-trust processing, AES as trust boundary, fail-closed behavior
• System Architecture — The AEON → AES → AEOS → consumer-selected Tonic/materializer pipeline
• Meaning & Parser Decisions — Why parser decisions must be visible; consumer-brings-the-contract
• Configuration Carcinisation — Why configs evolve into hidden languages, and how AEON contains it
• Spec Reference — Index of all normative specification documents

---

Current Baseline

• Language/spec line: AEON v1
• CTS line: v1
• Implementation/package line: 0.16.0
• Wiki role: explanatory guide; the spec and CTS repositories remain the authority for normative behavior

Links

• Implementation Website: aeon.altopelago.com
• Specification Website: aeonite.org
• Public Wiki: AltoPelago/aeon/wiki
• Specifications: aeonite-org/aeonite-specs
• Conformance Tests: aeonite-org/aeonite-cts
• Implementations: v0.16.0 in TypeScript, Rust, and Python