AEOS Schema Profile v1

Status: normative authoring profile for AEOS v1 schema documents

Canonical topic owners: ../AEOS-spec-v1.md, ../contracts/

This appendix defines the canonical AEON-authored schema document form for AEOS v1. It complements, and must project compatibly into, the shipped AEOS v1 SchemaV1 validator surface.

1. Scope and purpose

AEOS Schema Profile v1 defines the structure and interpretation of AEON documents used as schemas for AEOS validation.

It specifies:

• where schemas store rules, patterns, and charsets
• how rules bind data paths to constraints
• what kinds of references are allowed (and forbidden)
• strict separation between schema validation and data validation

This profile does not define pattern semantics — those are defined by AEOS Pattern Profile v1.

2. Fundamental model

AEOS validates data AES against schema AES.

AEOS NEVER:

• mutates either AES
• resolves data references
• coerces values
• interprets semantics beyond form

The .aeos document is the canonical human-authored schema format. SchemaV1 remains the canonical in-memory validator format. Loaders MUST project a valid .aeos document into a valid SchemaV1 object before validation begins.

Document header declarations are separate from schema authoring. An AEON document MAY declare:

In that model:

• schema is the primary schema id declared by the document producer.
• schemas is an optional object of additional named schema associations.
• Header schema declarations are descriptive metadata only; they do not dictate consumer processing behavior.
• A consumer MAY apply schema, MAY apply a named association from schemas, MAY ignore the declaration, or MAY enforce a local schema instead.
• If a consumer does choose among declared schema associations, schema is the default fallback.
• Context keys SHOULD use identifier-safe names with _ separators rather than ..

3. Schema document top-level shape

A Schema Profile v1 document MUST be an AEON document containing a top-level binding at canonical path $.aeos. That binding MUST be typed as schema.

Canonical form:

Rules:

• $.aeos MUST be present.
• The binding at $.aeos MUST carry datatype/type annotation schema.
• $.aeos.id MUST be present and MUST be a string.
• $.aeos.version MUST be present and MUST be a string.
• $.aeos.rules MUST be present.
• Any unknown top-level key under $.aeos is invalid:

• code = "invalid_schema_key"

Loader requirements:

• A .aeos loader MUST parse the document as normal AEON.
• It MUST locate $.aeos, confirm the schema type annotation, and materialize its object value.
• It MUST validate the schema-document contract before projection.
• It MUST project the materialized $.aeos object into a valid in-memory SchemaV1.

4. Rules section

4.1 Purpose

$.aeos.rules binds data paths to constraints.

Each rule applies independently; rule order has no semantic meaning.

4.2 Shape

Rules:

• rules MUST be an object.
• Each key MUST be a canonical AEON path.
• Each value MUST be a Rule Object.

Invalid:

• code = "invalid_rule_shape"

4.3 Rule Object

A Rule Object MAY contain the following keys:

Any other key is invalid:

• code = "invalid_rule_key"

Projection notes:

• reference_target_path is the preferred authoring surface.
• reference_target_pattern is an advanced fallback escape hatch.
• Loaders MUST project reference_target_path into an equivalent internal target-matching form before invoking AEOS.
• The resulting in-memory schema MUST remain compatible with the shipped SchemaV1 surface.

4.4 type constraint

Rules:

• type MUST be a literal-kind identifier.
• v1 supported kinds:

• StringLiteral
• IntegerLiteral
• FloatLiteral
• BooleanLiteral
• Reference

Semantics:

• AEOS checks only the literal kind emitted by AEON Core.
• No coercion is allowed.

Failure:

• runtime code = "type_mismatch"

4.5 apply_pattern

Rules:

• Value MUST be a string.
• The string MUST refer to a key in schema.patterns.

Invalid:

• code = "unknown_pattern"

Semantics:

• The referenced pattern is applied after type checking.
• The pattern MUST conform to Pattern Profile v1.
• The pattern is applied to the decoded string value.

5. Patterns section

5.1 Purpose

schema.patterns is a library of reusable pattern definitions.

Patterns are pure schema objects, not applied directly to data without a rule.

5.2 Shape

Rules:

• patterns MUST be an object.
• Each value MUST contain a Pattern Object as defined in Pattern Profile v1.
• Keys MUST be unique identifiers.

Invalid:

• code = "invalid_pattern_definition"

5.3 Pattern references

Pattern references:

• are resolved within the schema only
• MUST NOT reference data paths
• MUST NOT be recursive (directly or indirectly)

Recursive reference:

• code = "recursive_pattern_reference"

6. Charsets section

6.1 Purpose

schema.charsets defines named character sets used by pred.charset.

6.2 Shape

Rules:

• charsets MUST be an object.
• Charset definitions MUST conform to Pattern Profile v1 §6.

Invalid:

• code = "invalid_charset_definition"

7. Validation order (critical)

AEOS MUST apply constraints in the following strict order per rule:

1. Presence check

• If a rule exists for a path and the path is missing in data:

• runtime code = "missing_required_field"
• (v1: all rules are implicitly required)

1. Type check

• Validate literal kind against type
• On failure: STOP rule evaluation

1. Pattern check (if present)

• Apply referenced pattern
• On failure: STOP rule evaluation

Normative clarification: Patterns are never evaluated if the path is missing in data. A missing path fails at step 1 (presence check) before pattern evaluation is considered.

There is NO fallback, coercion, or continuation.

8. Reference handling (hard boundary)

8.1 Data references

If the data value at a rule path is a Reference:

• Type checking applies to the Reference literal itself
• Patterns MUST NOT be applied to Reference

Violation:

• runtime code = "constraint_inapplicable"

AEOS MUST NOT:

• resolve references
• peek at referenced values

8.2 Schema references

Schema-internal references are allowed only for:

• apply_pattern
• charset lookup

They are resolved once at schema load time, not per validation.

9. Error reporting

All rule failures MUST emit errors with:

• path = data path being validated
• span = span of the data literal (if available)
• phase = "schema_validation"
• code = appropriate code

If multiple rules fail, AEOS MUST report all failures (no short-circuit across rules).

10. Prohibitions (explicit)

AEOS Schema Profile v1 explicitly forbids:

• default value injection
• value coercion
• semantic validation (RFCs, calendars, etc.)
• schema-driven mutation of data
• schema rules depending on other rules’ results

Violation of these principles breaks conformance.

Clarification:

• The schema document loader MAY perform bounded projection work, including converting reference_target_path

into the internal target-matching representation required by AEOS v1.

• The AEOS validator itself still operates on SchemaV1, not on raw source text.

11. Conformance checklist

A conforming AEOS Schema Profile v1 implementation MUST:

• [ ] Require a top-level aeos:schema binding in .aeos documents
• [ ] Reject missing or mistyped $.aeos
• [ ] Reject unknown keys in $.aeos
• [ ] Enforce canonical path keys in rules
• [ ] Project .aeos documents into valid SchemaV1 objects before validation
• [ ] Enforce literal-kind-only type checks
• [ ] Apply patterns only after successful type check
• [ ] Resolve patterns only within schema scope
• [ ] Reject recursive pattern references
• [ ] Never mutate data AES or schema AES
• [ ] Emit spans from data AES in all rule failures
• [ ] Preserve phase ordering and fail-closed semantics

12. Minimal complete example