Epic G — Extract the normative inventory and publish coverage · Size XL · Release v1.63.0 · Blocked by: 443
Problem
Tiers 1 and 2 of the specification are published as JSON Schema, and epics A–D make oastools derive from them rather than transcribe them. Tier 3 has no machine-readable form at all — it exists only as prose in src/oas.md, 5,634 lines of it.
Tier 3 is where oastools earns its keep: $ref target existence, operationId uniqueness, path-template ↔ parameter agreement, RFC 6901 pointer escaping, discriminator mapping resolution. No JSON Schema validator can replicate any of it. But nothing today says which of those prose rules oastools actually implements.
For 3.2 the denominator is 115 MUST, 35 MUST NOT, 27 SHALL and 1 SHALL NOT — 178 normative statements, of which an unknown fraction is currently checked.
Approach
Parse RFC 2119 keyword sentences out of src/oas.md per version, anchored to their section IDs, and diff that inventory against the F2 registry.
The extraction is heuristic, and the deliverable is reviewed
This is the important constraint on scope. RFC 2119 keywords appear in non-normative prose ("implementations SHOULD find this convenient"), and some normative statements span sentences or depend on a preceding clause for their subject.
The deliverable is a reviewed inventory, not a generated one. Expect human curation on the first pass and drift review thereafter. A pipeline that emits 178 rows and calls it truth would produce a coverage number that is confidently wrong — worse than no number.
Acceptance
- An extractor produces candidate normative statements per version, each anchored to its
src/oas.md section ID.
- The curated inventory is checked in, with each entry marked covered (linked to a rule ID from the F2 registry) or uncovered.
- Re-running the extractor against a newer spec revision reports drift — new, removed and changed statements — rather than silently replacing the curated file.
- False positives from the heuristic are recorded as excluded-with-reason, so the next run does not resurface them.
Files
internal/codegen/ or scripts/ (extractor), checked-in curated inventory
Design: 2026-08-01-spec-conformance-gap-design.md · Plan: 2026-08-01-spec-conformance-gap-plan.md
Epic G — Extract the normative inventory and publish coverage · Size XL · Release v1.63.0 · Blocked by: 443
Problem
Tiers 1 and 2 of the specification are published as JSON Schema, and epics A–D make oastools derive from them rather than transcribe them. Tier 3 has no machine-readable form at all — it exists only as prose in
src/oas.md, 5,634 lines of it.Tier 3 is where oastools earns its keep:
$reftarget existence,operationIduniqueness, path-template ↔ parameter agreement, RFC 6901 pointer escaping, discriminator mapping resolution. No JSON Schema validator can replicate any of it. But nothing today says which of those prose rules oastools actually implements.For 3.2 the denominator is 115 MUST, 35 MUST NOT, 27 SHALL and 1 SHALL NOT — 178 normative statements, of which an unknown fraction is currently checked.
Approach
Parse RFC 2119 keyword sentences out of
src/oas.mdper version, anchored to their section IDs, and diff that inventory against the F2 registry.The extraction is heuristic, and the deliverable is reviewed
This is the important constraint on scope. RFC 2119 keywords appear in non-normative prose ("implementations SHOULD find this convenient"), and some normative statements span sentences or depend on a preceding clause for their subject.
The deliverable is a reviewed inventory, not a generated one. Expect human curation on the first pass and drift review thereafter. A pipeline that emits 178 rows and calls it truth would produce a coverage number that is confidently wrong — worse than no number.
Acceptance
src/oas.mdsection ID.Files
internal/codegen/orscripts/(extractor), checked-in curated inventoryDesign: 2026-08-01-spec-conformance-gap-design.md · Plan: 2026-08-01-spec-conformance-gap-plan.md