# Schema Contracts

## Supported Schemas
- `normalized_query_v1`
  - file: `backend/src/schemas/normalized_query_v1.json`
- `normalized_query_v2`
  - file: `backend/src/schemas/normalized_query_v2.json`
- `normalized_query_v2_0_1`
  - file: `backend/src/schemas/normalized_query_v2_0_1.json`
- `normalized_query_v2_0_2`
  - file: `backend/src/schemas/normalized_query_v2_0_2.json`

Root aliases in `/schemas`:
- `schemas/normalized_query_v2.json`
- `schemas/normalized_query_v2_0_1.json`
- `schemas/normalized_query_v2_0_2.json`

## v2.0.2 Additions
Fragment-level required fields:
- `execution_readiness`
- `route_status`
- `no_route_reason`

Enums:
- `execution_readiness`: `executable | executable_with_soft_assumptions | needs_clarification | no_route`
- `route_status`: `routed | no_route`
- `no_route_reason`: `out_of_scope | insufficient_specificity | missing_mapping | unsupported_fragment_type`

Consistency rules in schema:
- If `route_status=no_route` then `no_route_reason` must be non-null enum value.
- If `route_status=routed` then `no_route_reason` must be `null`.

## Validation API
Backend validates via AJV:
- `validateNormalized(payload, "v1")`
- `validateNormalized(payload, "v2")`
- `validateNormalized(payload, "v2_0_1")`
- `validateNormalized(payload, "v2_0_2")`