# Schemas

AXF is **schema-by-reference**: the envelope segment names a schema id,
and both sides of the wire are expected to know (or be able to fetch) the
schema definition. That's how AXF avoids paying for field names on
every message.

## File format

Schema files use the `.axf-schema` extension. They are themselves AXF
documents that describe the segment layout of another AXF document.
A bootstrapping schema (the schema-of-schemas, `meta.v1.axf-schema`) lives
at the well-known root and is self-describing.

Example skeleton:

```
FX*1.0*meta.v1*sch:tc.weather.v1~
S*FX*envelope*req~
S*H*header*req*role,ts,conv~
S*TC*tool_call*req*name,location,units,when~
S*M*metadata*opt*priority,timeout~
S*E*end*req~
E~
```

## Well-known directory pattern

Schemas are addressable in two ways:

1. **By short-id** (compact, requires a registry lookup):
   `tc:weather.v1`, `cm:chat.v1`, `evt:tool_result.v1`, …
   Short-ids are resolved via the public registry at
   `https://schemas.axf.ai/registry.json`.

2. **By URL** (self-contained, no registry needed):
   the envelope's schema element is the full URL of the `.axf-schema` file,
   e.g. `https://example.com/.well-known/axf/order.v3.axf-schema`.

By convention, organisations publishing their own schemas SHOULD host them
under:

```
https://<host>/.well-known/axf/<name>.<version>.axf-schema
```

This mirrors the `.well-known` pattern from RFC 8615.

## Versioning

Schema ids carry an explicit version suffix (`.v1`, `.v2`, …). A new
**major** schema version means breaking field changes; consumers MUST
pin to a major version. Adding optional trailing fields is **not**
breaking and does not require a major bump.

## Registry (planned)

`https://schemas.axf.ai/` will host:

- the canonical short-id ↔ URL registry,
- the bootstrap `meta.v1.axf-schema`,
- a small set of "core" schemas (`tc:*`, `cm:*`, `evt:*`) maintained by
  this repo.

To propose a core schema, follow the RFC process in
[`../CONTRIBUTING.md`](../CONTRIBUTING.md).