Introduction

Introduction

AEON is a human-readable, typed, semantics-first data notation.

At its core, an AEON document is a sequence of bindings:

key\identity\@{attributes}:type = value

That one line captures most of the language:

• key names the binding
• \identity\ optionally gives the structural occurrence a stable identity
• @{attributes} attaches optional metadata
• :type declares the intended datatype
• value holds the assigned value

In transport-oriented documents, AEON can also use a looser form:

key = value

Why AEON Exists

AEON is designed for documents that need more structure and meaning than plain JSON or YAML, while still staying readable and writable by people.

AEON focuses on:

• explicit datatypes
• deterministic interpretation
• stable addressing and references
• clear structural syntax
• canonical rendering

You can think of it as sitting somewhere between JSON and XML: it keeps structured data front and center, while borrowing some of the clearer separation of concerns that made HTML-style systems durable and easy to reason about.

For the broader system view, see Key Features. That page explains how determinism, typed transport, canonical form, addressing, references, annotation streams, AEOS validation, and non-executable design fit together.

The Basic Mental Model

An AEON document is made of bindings. Each binding assigns a value to a key.

name:string = "AEON"
build:number = 1
active:toggle = on

This example shows three common ideas:

• bindings are written one per line
• datatypes are explicit in typed modes
• values use dedicated literal families such as strings, numbers, and switches

Core Syntax

The canonical binding surface is:

key\identity\@{attributes}:type = value

Common pieces of syntax:

• = assigns a value
• : introduces a datatype annotation
• \id\ adds optional structural identity metadata before attributes and datatype
• @{...} adds attributes
• , and newline act as structural separators depending on context
• ~name and ~>name express explicit references

Keys

Keys may be bare or quoted.

Bare keys are useful when they are identifier-safe:

user = 1
_internal = 2
build42 = 3

Quoted keys are used when the key contains spaces, dots as data, or other non-bare characters:

"user name" = 1
"a.b" = 2
'display label' = 3

Attributes

Attributes attach metadata to a binding head or node head.

user@{role:string = "admin", level:number = 5}:object = {
  id:number = 1
}

Attributes come before the datatype annotation:

key@{meta = "x"}:type = value

Not:

key:type@{meta = "x"} = value

Structural identity comes before attributes and datatype:

key\id\@{meta = "x"}:type = value

It is preserved as metadata and does not change the binding's canonical path.

Lists, tuples, and node children can also carry anonymous local heads:

values:list = [\v1\:number = 3, \v2\@{unit:string = "cm"}:number = 4]

These heads annotate the immediate anonymous child. They are not root bindings and they are not object members.

Values

AEON supports a small reusable set of value families.

Scalars:

title:string = "Hello"
count:number = 42
enabled:boolean = true
feature:toggle = on
color:hex = #FF00AA
bits:radix = %1011
price:decimal = %19.9900
blob:encoding = &QmFzZTY0IQ==

Temporal values:

day:date = 2025-01-01
time:time = 09:30Z
stamp:datetime = 2025-01-01T09:30:00Z
meeting:wtc = 2025-01-01T09:30:00Z&Australia/Melbourne

Containers:

settings:object = {
  theme:string = "dark"
  retries:number = 3
}

items:list = ["a", "b", "c"]
measurements:list = [@{unit:string = "cm"}:number = 3]
point:tuple = (:number = 1, :number = 2)
rgb:triple<number, number, number> = (255, 128, 0)

Separator literals:

size:sep["x"] = ^300x250
path:sep = ^"root/main/file.aeon"

References

AEON has explicit reference syntax.

Clone-like references preserve value-copy intent:

origin:number = 1
copy:number = ~origin

Pointer-like references preserve pointer intent:

origin:number = 1
alias:number = ~>origin

References are deterministic and fail closed when invalid. Forward references, missing targets, and illegal self-references are rejected.

Nodes

AEON also supports tagged node values:

content:node = <article(
  <h1("Hello")>,
  <p("World")>
)>

Nodes are useful when document structure needs tagged child-bearing values rather than only plain object/list containers.

Node children use the same indexed child model as lists and tuples, so a schema or reference can target paths such as $.content[0].

Modes

AEON Core v1 defines three behavior modes:

• transport
• strict
• custom

In practice:

• transport allows untyped non-header bindings and allows custom datatype labels
• strict requires datatype annotations and defaults to the reserved core datatype surface
• custom also requires datatype annotations, but allows custom datatype labels

Examples:

// transport-style
name = "AEON"

// strict-style
name:string = "AEON"

// custom-style
name:label = "AEON"

A Small Example

aeon:mode = "strict"

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

This document shows:

• a header binding
• an object value
• typed child bindings
• multiple literal families
• the current AEON v1 typed-mode style

Where To Go Next

If you are new to AEON, the most useful next topics are:

1. Structure Syntax
2. Value Types
3. Addressing and References
4. Comments and Annotations
5. Canonical Form

For the authoritative v1 rules, see the spec set:

• AEON-spec-v1.md
• structure-syntax-v1.md
• value-types-v1.md
• addressing-references-v1.md
• comments-annotations-v1.md

This page is intentionally a compact introduction. The detailed edge cases and behavioral guarantees live in the formal specifications.