AEON Specification v1

Status: official v1 overview Scope: normative overview of AEON Core v1, its boundaries, and the companion reference set.

1. What AEON Is

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

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

Implementations may accept looser transport forms, but this overview defines the Core v1 model and points to the detailed companion references.

2. Smallest Useful Example

This demonstrates:

• key/value assignment
• explicit datatype annotation
• deterministic literal interpretation

3. Document Model

AEON Core v1 is built from a small set of structural ideas:

• bindings
• keys
• values
• attributes
• references
• canonical paths
• comments/annotations

Bindings are separated by newline or comma at document/object level and may contain structured values such as objects, lists, tuples, nodes, and references.

4. Core Value Families

Core value families include:

• strings
• numbers
• infinity literals
• booleans
• switches
• hex, radix, and encoding literals
• date, time, datetime, and ZRUT forms
• objects, lists, tuples, and nodes
• clone and alias references
• separator literals

Normative detailed reference:

• value-types-v1.md

5. Structural Syntax Surface

Core structural syntax includes:

• bare and quoted keys
• attribute blocks
• nested attribute heads
• datatype annotations
• separator specs
• comma/newline element separation rules
• comma/newline binding rules

Quoted keys are part of Core v1 syntax, but empty quoted keys are invalid.

Normative detailed reference:

• structure-syntax-v1.md

6. Addressing and References

AEON Core v1 provides:

• canonical path identity using root/member/index segments
• quoted-segment disambiguation
• index-based element addressing
• attribute selectors for attribute-namespace traversal
• deterministic reference legality rules

Reference legality is fail-closed:

• forward references are invalid
• missing targets are invalid
• self-references are invalid

Normative detailed reference:

• addressing-references-v1.md

7. Comments and Annotation Channels

AEON distinguishes:

• plain comments
• structured annotation channels
• reserved structured channels

Comments do not alter parse semantics, path identity, reference legality, or assignment ordering.

Structured comments may attach deterministically to neighboring targets and may be emitted as a separate annotation stream.

Normative detailed reference:

• comments-annotations-v1.md

8. Behavior Modes and Datatype Policy

AEON Core v1 defines three behavior modes:

• transport
• strict
• custom

aeon:mode / aeon:header.mode is a declared document mode. It records the author's intended processing discipline, but it is not authoritative over the processor.

Processors apply an effective mode when enforcing mode-dependent rules:

• the effective mode MAY be selected by processor/runtime configuration;
• the effective mode MAY be inferred from the declared document mode when no external policy is supplied;
• processor/runtime configuration MUST remain authoritative when it supplies an effective mode;
• a document-declared mode MUST NOT force a processor to become stricter, looser, or custom-enabled against processor policy.

Effective mode resolution:

Core v1 behavior under the effective mode is:

• transport may omit datatype annotations and accepts custom datatype labels
• strict requires datatype presence and accepts only the reserved Core datatype surface by default
• custom requires datatype presence and accepts custom datatype labels
• explicit datatype annotations are validated in all modes

Implementations MAY still expose an explicit datatype-policy override as an implementation control. Datatype policy applies to the effective mode, not merely to a document-declared mode claim.

Authoritative compliance requirements and behavioral floors are defined in:

• AEON-v1-compliance.md

9. Deterministic Policy Knobs

Core v1 requires deterministic depth-policy controls for:

• max_attribute_depth
• max_separator_depth
• max_generic_depth

Core v1 also defines an optional event-budget control:

• max_events

Reference implementation defaults lock the depth-policy controls to 1, while conforming implementations must support a capability floor of at least 8.

When max_events is configured, implementations MUST fail closed if the emitted AES event count exceeds the configured value. This limit is a consumer-side resource budget and does not change source syntax or canonical path assignment.

10. Phase Boundaries

AEON Core is responsible for:

• lexical analysis
• parsing
• canonical path assignment
• reference legality
• annotation-stream extraction when enabled

Core does not define downstream application semantics such as:

• domain validation meaning
• profile-specific projection decisions
• schema/business-rule interpretation

AEOS/schema/profile layers build on top of Core rather than redefining it.

Document-declared conventions, profiles, and schemas are advisory until selected or trusted by the consumer/processor. They do not self-activate.

The standard GP security envelope, when used, is convention-driven. It is represented as a normal top-level object binding typed as :envelope rather than a Core-special key:

• aeon.gp.security.v1 defines the envelope structure
• aeon.gp.integrity.v1 defines canonical integrity hashing
• aeon.gp.signature.v1 defines signature representation
• aeon.gp.encryption.v1 defines encryption metadata representation

Header placement is part of Core syntax:

• shorthand header bindings (aeon:mode, aeon:profile, aeon:schema, aeon:version, etc.) form the document header only when they appear in the initial header block at the start of the document;
• a structured header (aeon:header = { ... }) MUST appear before any body binding;
• a structured header that appears after any body binding is invalid.

11. Conformance Surface

Normative conformance requirements are defined in:

• AEON-v1-compliance.md
• AEOS-spec-v1.md
• conformance-matrix.md

CTS protocol and lane baselines:

• cts/protocol/v1
• cts/core/v1
• cts/aes/v1
• cts/annotations/v1
• cts/aeos/v1

Core conformance should be reviewed by backbone behavior family, not only by individual suite file.

Current v1 backbone families are:

• canonical rendering and node normalization
• fail-closed parsing and deterministic rejection behavior
• addressing and canonical path semantics
• quoted-key and traversal disambiguation
• attribute traversal and attribute-depth semantics
• annotation attachment and slash-channel binding
• strict literal acceptance and rejection boundaries
• separator/path literal handling
• datatype-to-literal validation behavior

The anti-drift coverage state for those families is tracked in aeonite-cts/CONFORMANCE-COVERAGE.md.

12. Contracts

Canonical baseline v1 contracts are provided in:

• ../../../contracts/v1/drafts/artifacts/registry.json
• ../../../contracts/v1/drafts/artifacts/profiles/aeon.gp.profile.v1.aeon
• ../../../contracts/v1/drafts/artifacts/schemas/aeon.gp.schema.v1.aeon

These contracts are authoritative artifacts for the baseline general-purpose profile/schema set. They are official baseline contracts, not implicit defaults when no trusted profile/schema is selected.

13. Companion Reference Set

The official v1 documentation is intentionally split by concern:

• AEON-spec-v1.md — overview and boundaries
• AEON-v1-compliance.md — mandatory conformance requirements
• AEOS-spec-v1.md — AEOS validation layer
• value-types-v1.md — value families and literal forms
• structure-syntax-v1.md — keys, attributes, separators, newline behavior
• addressing-references-v1.md — canonical paths and reference rules
• comments-annotations-v1.md — comment channels and attachment behavior
• appendices/appendix-directive-block-capabilities.md — informative v1 reservation for capability-based evolution

This overview should stay short and stable. Detailed syntax, examples, and edge-case rules belong in the companion references.

14. Anti-Drift Requirement

AEON Core conformance is not satisfied by passing a small representative sample.

A conforming implementation must preserve behavior across the Core backbone families named above and their corresponding CTS lanes, especially:

• canonical output and normalization behavior
• fail-closed invalid syntax handling
• canonical path identity and quoted-key disambiguation
• reference legality and attribute traversal behavior
• annotation attachment behavior
• strict literal acceptance and rejection boundaries

Behavior must remain stable across implementations so the canonical backbone of the format does not fragment.