<!-- Schemas -->

# Describe what a document is allowed to contain.

AEON keeps structure and validation separate. A document can stay readable and expressive, while AEOS¹ defines what paths, value kinds, reference forms, and attribute payloads are acceptable.

That makes validation visible rather than hidden inside application code.

[See the schema shape](#shape)  
[See the validation flow](#flow)  
[Open AEOS playground](/aeos-playground.php)  
[Read the wiki page](https://github.com/AltoPelago/aeon/wiki/AEOS-Schema-Validation)

<!-- Schema Shape -->

## A schema can express the expected structure directly.

The schema² states required paths and the kinds of values they accept. A validator checks AES³ against that contract⁴ without changing the document itself.

```aeon
aeos:schema = {
  id:string = "altopelago.schema.example.v0.9"
  version:string = "1"
  world:string = "open"
  rules:list<object> = [
    {
      path:string = "$.document.title"
      constraints:object = {
        required:boolean = true
        type:string = "StringLiteral"
        datatype:string = "string"
      }
    }
    {
      path:string = "$.document.published"
      constraints:object = {
        type:string = "BooleanLiteral"
      }
    }
    {
      path:string = "$.document.tags"
      constraints:object = {
        type:string = "ListNode"
        type_is:string = "list"
      }
    }
    {
      path:string = "$.document.measurements[0]"
      constraints:object = {
        type:string = "NumberLiteral"
        attributes:object = {
          unit:object = {
            required:boolean = true
            type:string = "StringLiteral"
          }
        }
        closed_attributes:boolean = true
      }
    }
  ]
}
```

<!-- Validation Flow -->

## The document and the schema remain separate artifacts.

The document remains ordinary AEON. Validation is a later step that confirms whether the document satisfies the contract you chose to apply.

```aeon
document:object = {
  title:string = "Release notes"
  published:boolean = true
  tags:list = ["spec", "draft"]
  measurements:list = [@{unit:string = "cm"}:number = 3]
}
```

<!-- Validation Result -->

## Failures stay explainable because the contract is explicit.

Because the schema is visible, validation failures can be explained in terms of the document itself: wrong value kind, missing path, unexpected binding, or missing attribute metadata. That is easier to reason about than hidden runtime assumptions.

```aeon
document:object = {
  title:string = "Release notes"
  published:string = "yes"
  tags:list = ["spec", 42]
  measurements:list = [@{precision:number = 2}:number = 3]
}
```

<!-- Further Reference -->

## Use the full AEOS reference for validator detail.

The fuller AEOS reference covers constraints, indexed child paths, selector rules, attribute-aware checks, result envelopes, diagnostic codes, and AEOS authority boundaries.

The formal specification and CTS remain the authority for normative validator behavior.

## Definitions

¹ **AEOS:** the AEON schema layer. AEOS validates shape, required fields, declared types, and structural constraints; it does not prove business truth or domain meaning by itself.

² **Schema:** a validation document or rule set that checks form: existence, required fields, declared types, shape, and structural constraints.

³ **AES:** Assignment Event Stream. The ordered preservation artifact produced from AEON source, used by later validation, canonicalization, auditing, and materialization steps.

⁴ **Contract:** an explicit agreement a consumer can verify against, usually combining expectations about schemas, profiles, accepted claims, and materialization rules.