# Schemas and Contract Families

**Status:** Approved target-state baseline  
**Executable schema implementation:** increment-scoped; semantic ownership is specified now.

## Purpose

Define the cross-cutting machine-readable contract families AWP implementation must create without allowing JSON/OpenAPI/provider schemas to become a second domain model.

```text
Domain semantics
  -> schema family / DTO/event/adapter contract
  -> generated/runtime validators and typed contracts
  -> transport/provider/config persistence
```

## Families

- [Identifiers and Versioning](identifiers-versioning.md)
- [Transport Contracts](transport-contracts.md)
- [Events and Audit](events-audit.md)
- [Configuration Schemas](configuration.md)
- [Adapter Contracts](adapters.md)

Concrete executable artifacts may live in code packages such as `packages/contracts` or generated OpenAPI/JSON Schema, but these specifications own their semantics and compatibility boundaries.

## Invariants From Day 1

- schema names/types use AWP vocabulary, not vendor SDK objects;
- stable AWP IDs and revisions are explicit;
- `schemaVersion`/payload versions are separate from resource revision;
- mutation contracts support idempotency/correlation/precondition where needed;
- errors are typed and recoverable by UI/CLI/MCP;
- sensitive values use references/redaction/classification;
- events distinguish durable business fact from audit/telemetry/realtime;
- provider adapter schemas include capability/error/reconciliation semantics;
- compatibility promises are explicitly declared; not every internal dogfood type is frozen;
- once a stable/external boundary exists, R4 compatibility checks protect it.

## Increment Realization

I0 creates core ID/error/config/event/provider contract validators. Each increment adds executable schemas for newly activated domains. Full target schema families are specified now so ownership/versioning do not drift.

## Current Implementation State

Specification baseline only. Exact generated file layout/tooling is an implementation detail if it preserves these contracts.

## Temporary Dogfood Behavior

A single internal API version is acceptable before public consumers, but persisted/events/provider references still carry enough version/revision identity for safe evolution.

## Acceptance

An implementation agent can decide where a schema belongs, what owns its meaning, how to version it and when a breaking change needs compatibility treatment without inventing a new authority.