Initial import NDC_1C

llm_normalizer/docs/SCHEMA.md

@@ -0,0 +1,38 @@
+# 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")`