OpenAPI 3.1 / 3.2 Conformance: master tracking issue

[lightsofapollo]

OpenAPI 3.1 / 3.2 Conformance — Master Tracking Issue

This is the single source-of-truth issue for getting the generator to honestly support OpenAPI 3.1 and 3.2. We will comment on this issue as work progresses rather than filing 50+ child issues.

Background

Six parallel audit agents reviewed the codebase against the OpenAPI 3.1.2 (2025-09-19) and OpenAPI 3.2.0 (2025-09-19) specs. Reports live under tmp/openapi-specs/reports/ (and 00-SUMMARY.md consolidates).

Headline finding: the README claims OpenAPI 3.1 support; in practice the generator is OpenAPI 3.0-shaped with a thin 3.1 veneer. A 3.1- or 3.2-only spec parses without error and silently drops most semantics. Architectural root cause: every parsing struct ends with #[serde(flatten)] extra: BTreeMap<String, Value> and there is no deny_unknown_fields anywhere.

Conformance harness

The repo now contains a self-validating conformance harness:

• tests/conformance/specs/ — committed copies of OAS 3.1.2 and 3.2.0 markdown.
• tests/conformance/catalog.yaml — generated from the 3.2.0 spec by cargo run --bin catalog-gen. 30 OAS Objects, 141 fields, 57 JSON Schema 2020-12 keywords, 7 parameter-style combos. This is the denominator for "100% coverage".
• tests/conformance/fixtures/ — atomic fixtures, each tagged with coverage: entries from the catalog and a fails_at: L0|L1|L3|... marker. The harness (tests/conformance.rs) only enforces ACTIVE_LAYERS; later layers light up as they are implemented.
• tests/conformance/external/json-schema-test-suite/ — git submodule of the canonical JSON Schema 2020-12 corpus. Run via tests/conformance_json_schema.rs.
• tests/conformance/external/apis-guru-sync.sh — lazy-clones the APIs.guru openapi-directory for nightly real-world smoke (APIS_GURU_SMOKE=1).
• tests/conformance/status.toml — honest support claims, derived from harness results. README will pull from this.

Beads — units of independently-mergeable work

All 51 beads + 4 epics are described in tests/conformance/beads.yaml. The tables below are a rendered view; edit beads.yaml as the source of truth.

Parallelization rule: two beads may run concurrently iff their files sets are disjoint AND neither is in the other's depends_on closure.

Phase 0

	ID	Title	Area	Files	Depends on
[ ]	F1	Add #[serde(deny_unknown_fields)] across spec structs + version validator	foundation	src/openapi.rs src/cli.rs	—
[ ]	F2	Schema enum supports type as array (3.1 canonical nullability)	schema	src/openapi.rs src/analysis.rs	F1
[ ]	F3	Reference Object as sum type for non-Schema reusable objects	refs	src/openapi.rs src/analysis.rs	F1
[ ]	F4	Accept paths-less specs (components-only and webhooks-only)	components	src/analysis.rs	F1

Phase 1

	ID	Title	Area	Files	Depends on
[ ]	T1	Wire header request parameters through codegen	codegen	src/client_generator.rs src/analysis.rs	F1
[ ]	T2	Emit operations for options/head/patch/trace HTTP methods	codegen	src/client_generator.rs src/registry_generator.rs	F1
[ ]	T3	Honor auth_config ApiKey + Custom variants	security	src/client_generator.rs src/config.rs README.md	F1
[ ]	T4	Walk webhooks: in analysis	webhooks	src/openapi.rs src/analysis.rs src/client_generator.rs	F1, F3
[ ]	T5	Path templating percent-encoding	codegen	src/client_generator.rs	F1
[ ]	T6	Detect operationId collisions	codegen	src/analysis.rs	F1
[ ]	T7	Handle non-JSON success response bodies	bodies	src/analysis.rs src/client_generator.rs	F1
[ ]	T8	Wire range status codes (2XX/4XX/5XX)	bodies	src/client_generator.rs src/analysis.rs	F1
[ ]	T9	Model Response Header object (typed response headers)	bodies	src/openapi.rs src/client_generator.rs	F1, F3
[ ]	T10	Resolve $ref-typed parameter types	refs	src/client_generator.rs src/analysis.rs	F1, F3
[ ]	T11	requestBody required:false → Option	bodies	src/client_generator.rs src/analysis.rs	F1
[ ]	T12	additionalProperties: → BTreeMap<String, T>	schema	src/analysis.rs	F1
[ ]	T13	Surface description/summary/deprecated/tags into rustdoc + module structure	codegen	src/client_generator.rs src/registry_generator.rs	F1
[ ]	T14	Implement parameter style/explode matrix (RFC6570)	paths	src/openapi.rs src/analysis.rs src/client_generator.rs	F1
[ ]	T15	SSE streaming auto-detection from text/event-stream responses	bodies	src/streaming.rs src/analysis.rs	F1

Phase 2

	ID	Title	Area	Files	Depends on
[ ]	H1	Model Server Object + Server Variable + multi-server runtime	security	src/openapi.rs src/client_generator.rs src/cli.rs	F1
[ ]	H2	Model SecurityScheme (apiKey/http/oauth2/openIdConnect/mutualTLS)	security	src/openapi.rs src/client_generator.rs src/streaming.rs	F1, T3
[ ]	H3	Model SecurityRequirement (AND/OR + per-op + empty)	security	src/openapi.rs src/client_generator.rs	H2
[ ]	H4	Model Encoding Object (multipart + form-urlencoded)	bodies	src/openapi.rs src/client_generator.rs	F1
[ ]	H5	Model Header Object as request and response	bodies	src/openapi.rs	F1, F3
[ ]	H6	Model Example Object (object map; remove deprecated singular example)	bodies	src/openapi.rs	F1, F3
[ ]	H7	Model Link Object + runtime expressions	components	src/openapi.rs	F1, F3
[ ]	H8	Model Callback Object	components	src/openapi.rs src/analysis.rs	F1, F3, T4
[ ]	H9	Model Tag Object + tag-based module organization	tags	src/openapi.rs src/client_generator.rs src/analysis.rs	F1, T13
[ ]	H10	Model ExternalDocs	components	src/openapi.rs	F1
[ ]	H11	Path Item $ref + components/pathItems bucket	components	src/openapi.rs src/analysis.rs	F1, F3
[ ]	H12	Discriminator allOf-parent polymorphism + not keyword	schema	src/openapi.rs src/analysis.rs	F1

Phase 2b

	ID	Title	Area	Files	Depends on
[ ]	J1	$dynamicRef / $dynamicAnchor (replace $recursiveRef)	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J2	$defs enumeration in extract_schemas	schema	src/analysis.rs	F1
[ ]	J3	Validation keywords as runtime checks (validator crate)	schema	src/openapi.rs src/generator.rs	F1
[ ]	J4	prefixItems (tuple types)	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J5	patternProperties + propertyNames	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J6	unevaluatedProperties / unevaluatedItems	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J7	dependentSchemas / dependentRequired	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J8	contains / minContains / maxContains; contentEncoding/MediaType/Schema	schema	src/openapi.rs src/analysis.rs	F1
[ ]	J9	format coverage: date-time, uuid, byte, binary, email, uri	schema	src/analysis.rs	F1
[ ]	J10	jsonSchemaDialect at root; remove 3.0 nullable	schema	src/openapi.rs src/analysis.rs	F1, F2

Phase 3

	ID	Title	Area	Files	Depends on
[ ]	D1	PathItem.additionalOperations + query method	paths	src/openapi.rs src/analysis.rs src/client_generator.rs	F1, T2
[ ]	D2	Parameter in: querystring	paths	src/openapi.rs src/analysis.rs src/client_generator.rs	F1
[ ]	D3	MediaType.itemSchema / prefixEncoding / itemEncoding	bodies	src/openapi.rs src/analysis.rs src/client_generator.rs	F1, H4
[ ]	D4	OAuth deviceAuthorization flow + oauth2MetadataUrl	security	src/openapi.rs	F1, H2
[ ]	D5	Tag.kind / parent / summary	tags	src/openapi.rs src/client_generator.rs	F1, H9
[ ]	D6	$self keyword + Appendix F/G base URI rules	refs	src/openapi.rs src/analysis.rs	F1
[ ]	D7	Components.mediaTypes bucket	components	src/openapi.rs src/analysis.rs	F1
[ ]	D8	Server.name field	security	src/openapi.rs	F1, H1
[ ]	D9	Discriminator.defaultMapping	schema	src/openapi.rs src/analysis.rs	F1, H12
[ ]	D10	SecurityScheme.deprecated	security	src/openapi.rs src/client_generator.rs	F1, H2

Parallel-execution batches

Beads grouped by dependency depth. Within a depth tier, beads with disjoint file sets can be worked in parallel; beads sharing files must serialize.

Tier 0

• Batch 0.1: F1 (touches src/cli.rs, src/openapi.rs)

Tier 1

• Batch 1.1: F2, T2 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs, src/registry_generator.rs)
• Batch 1.2: F3, T3 (touches README.md, src/analysis.rs, src/client_generator.rs, src/config.rs, src/openapi.rs)
• Batch 1.3: F4, T5, H10 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 1.4: T1, J3 (touches src/analysis.rs, src/client_generator.rs, src/generator.rs, src/openapi.rs)
• Batch 1.5: T6, T13 (touches src/analysis.rs, src/client_generator.rs, src/registry_generator.rs)
• Batch 1.6: T7 (touches src/analysis.rs, src/client_generator.rs)
• Batch 1.7: T8 (touches src/analysis.rs, src/client_generator.rs)
• Batch 1.8: T11 (touches src/analysis.rs, src/client_generator.rs)
• Batch 1.9: T12, H1 (touches src/analysis.rs, src/cli.rs, src/client_generator.rs, src/openapi.rs)
• Batch 1.10: T14 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 1.11: T15, H4 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs, src/streaming.rs)
• Batch 1.12: H12 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.13: J1 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.14: J2 (touches src/analysis.rs)
• Batch 1.15: J4 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.16: J5 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.17: J6 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.18: J7 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.19: J8 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.20: J9 (touches src/analysis.rs)
• Batch 1.21: D2 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 1.22: D6 (touches src/analysis.rs, src/openapi.rs)
• Batch 1.23: D7 (touches src/analysis.rs, src/openapi.rs)

Tier 2

• Batch 2.1: T4 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 2.2: T9 (touches src/client_generator.rs, src/openapi.rs)
• Batch 2.3: T10, H5 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 2.4: H2 (touches src/client_generator.rs, src/openapi.rs, src/streaming.rs)
• Batch 2.5: H6 (touches src/openapi.rs)
• Batch 2.6: H7 (touches src/openapi.rs)
• Batch 2.7: H9 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 2.8: H11 (touches src/analysis.rs, src/openapi.rs)
• Batch 2.9: J10 (touches src/analysis.rs, src/openapi.rs)
• Batch 2.10: D1 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 2.11: D3 (touches src/analysis.rs, src/client_generator.rs, src/openapi.rs)
• Batch 2.12: D8 (touches src/openapi.rs)
• Batch 2.13: D9 (touches src/analysis.rs, src/openapi.rs)

Tier 3

• Batch 3.1: H3 (touches src/client_generator.rs, src/openapi.rs)
• Batch 3.2: H8 (touches src/analysis.rs, src/openapi.rs)
• Batch 3.3: D4 (touches src/openapi.rs)
• Batch 3.4: D5 (touches src/client_generator.rs, src/openapi.rs)
• Batch 3.5: D10 (touches src/client_generator.rs, src/openapi.rs)

How we'll work

1. Phase 0 lands first as a single PR (or as F1, F2, F3, F4 in sequence). Without deny_unknown_fields, every later fix is unverifiable.
2. Each subsequent bead is a focused PR, scoped to its files set, with a conformance fixture flipping from fails_at: failing to passing.
3. Progress is tracked in this issue's comments: one comment per merged bead with the bead ID, PR link, and which status.toml entries flipped.
4. We don't stage 50 child issues — the granularity lives in beads.yaml and PR titles. This issue is the dashboard.
5. Honesty gate: tests/conformance/status.toml is regenerated by the harness; the README's support claims will be derived from it. Drift fails CI.

References

• Audit reports: tmp/openapi-specs/reports/00-SUMMARY.md and per-area files (01-schema, 02-paths-parameters, 03-bodies-media, 04-servers-security, 05-components-refs-webhooks, 06-three-two-deltas).
• Spec: tests/conformance/specs/openapi-3.2.0.md, openapi-3.1.2.md.
• Catalog: tests/conformance/catalog.yaml.
• Beads source-of-truth: tests/conformance/beads.yaml.

[lightsofapollo]

F1 ✅ — Strict spec extensions + version gate

Branch: feat/conformance-3.1-3.2 · Commit: 6d4ee09

What changed

• Replaced extra: BTreeMap<String, Value> on every non-Schema spec struct with a typed Extensions newtype that rejects any non-x- key at deserialize time.
• Added typed fields for previously-flattened spec data on OpenApiSpec, Info, Components, PathItem, Operation, Parameter, Response, MediaType, RequestBody, and Discriminator. Things like webhooks, pathItems (3.1+), mediaTypes (3.2), style/explode, tags, deprecated, securitySchemes, etc. now land in named fields instead of being lost.
• CLI version gate: 3.0.x and 3.1.x first-class, 3.2.x emits an "experimental" warning, anything else hard-errors.

Note on deny_unknown_fields: cannot combine with #[serde(flatten)] — the former rejects fields before the flatten target sees them, including x-* extensions. Using Extensions with a custom Deserialize is the canonical workaround: any non-x-* unknown field lands in Extensions and fails its prefix check there.

Schema family unchanged for now. Schema and SchemaDetails keep the loose extra because analysis.rs reads JSON-Schema-2020-12 keywords (patternProperties, propertyNames, dependentRequired, if/then/else, …) directly from there. Those graduate to typed fields under J5–J8.

Conformance impact

• 5 fixtures advanced from fails_at: L0 → fails_at: L3 (root-level fields are now typed; codegen still doesn't act on them):
  • webhooks/basic-webhook.yaml
  • components/path-items-component.yaml
  • components/media-types-component-3.2.yaml
  • security/mutual-tls.yaml
  • schema/dynamic-ref-tree.yaml (the document-level jsonSchemaDialect field; the inner $dynamicRef/$dynamicAnchor still need J1)
• parameter/deepobject-query.yaml also advances — style/explode are typed but codegen still collapses object query params to String (T14).
• 205/205 unit tests pass. No regressions in the existing test_openai_responses_fixture, test_anthropic_fixture, etc.

Next: F2 (Schema enum supports type as array — 3.1 canonical nullability).

[lightsofapollo]

Batch progress — 32 of 51 beads landed (≈ 63%)

Branch: feat/conformance-3.1-3.2. All commits keep cargo test --tests at 205/205 green.

Completed beads

Phase	Status	Beads
Phase 0 — Foundation	3/4	F1 ✅ F2 ✅ F4 ✅ — F3 (MaybeRef<T> sum type) deferred; ad-hoc reference: Option<String> field on each is functionally equivalent for now
Phase 1 — Top silent failures	11/15	T1 T2 T3 T4 T5 T6 T8 T10 T11 T13 T15 ✅ — T7 (non-JSON success), T9 (success-path response headers), T12 (typed additionalProperties), T14 (full RFC6570 style/explode matrix) deferred
Phase 2 — Honest 3.1 (struct families)	9/12	H1 H2 H4 H5 H6 H7 H8 H9 H10 ✅ — H3 (per-op security override emission), H11 ($ref Path Item resolution), H12 (allOf-parent polymorphism) deferred
Phase 2b — JSON Schema 2020-12	1/10	J1 ✅ ($dynamicRef + $dynamicAnchor typed) — J2…J10 deferred
Phase 3 — 3.2 deltas	8/10	D1 D3 D4 D5 D7 D8 D9 D10 ✅ — D2 (in: querystring) and D6 ($self resolution) deferred

Highlights

• Extensions newtype replaces serde(flatten) extra: BTreeMap on every non-Schema struct. Any field not modeled or starting with x- now fails to deserialize, surfacing what the audit identified as the architectural root cause.
• Webhooks, additionalOperations, query HTTP method all parse and produce client methods — including custom verbs via reqwest::Method::from_bytes.
• Schema::TypedMulti added before Typed so 3.1's type: ["string", "null"] deserializes correctly and propagates nullability into AnalyzedSchema.
• Schema::DynamicRef + SchemaDetails.$dynamicAnchor / $id. Resolution treats it like $recursiveRef for now; full anchor-scope resolution is a future J-bead.
• All 5 Security Scheme types modeled (apiKey/http/oauth2/openIdConnect/mutualTLS) with full OAuth2 flow set including 3.2 device authorization + oauth2MetadataUrl + deprecated.
• Server, ServerVariable, Tag, ExternalDocs, Header, Example, Link, Callback, Encoding all promoted from Value blobs to typed structs. 3.2 Tag fields (summary, parent, kind) modeled.
• CLI version gate: 3.0.x and 3.1.x first-class, 3.2.x emits an experimental warning, anything else is a hard error.
• auth_config ApiKey/Custom variants now actually reach codegen instead of being silently rewritten to bearer_auth.
• Path templating percent-encodes per RFC 3986 §3.3 via an emitted __pct_encode_path_segment helper.
• HTTP methods: OPTIONS/TRACE no longer silently rewrite to GET; PATCH/HEAD use named reqwest methods.
• Range status codes (2XX/4XX/5XX) compile to guarded match arms instead of falling through to default.
• operationId collisions error loudly with both colliding paths.
• rustdoc now carries operation summary + description from the spec, plus the method+path in backticks.
• SSE auto-detect from text/event-stream response content types.
• Header request parameters flow through to req.header(name, value).

Updated tests/conformance/status.toml

33 entries: 22 supported, 6 partial, 5 unsupported. Each partial / unsupported still has a precise pointer to the remaining work.

Deferred (intentional, with notes)

Bead	Reason for defer
F3	MaybeRef<T> enum across Parameter/RequestBody/Response/Header/Example/Link/Callback. Functionally covered for now by the reference: Option<String> field on each; full sum-type is a Phase 0 follow-up.
T7	Requires changing OperationInfo.response_schemas from BTreeMap<String, String> to a richer type carrying content-type + Rust target. Touches the codegen response branch.
T9	Surface-path response headers — depends on T7's response-shape refactor.
T12	additionalProperties: <schema> → typed BTreeMap<String, T>. Requires extending SchemaType::Object.additional_properties: bool to an AdditionalPropertiesType enum and threading it through every codegen site.
T14	Full RFC6570 parameter style/explode matrix. ≥7 styles × explode × in × type — best done as its own focused PR with a wiremock test per combination.
H11	pathItems component lookup + Path Item $ref resolution at analysis time.
J2…J10	Schema-keyword expansion ($defs, prefixItems, patternProperties, validation as runtime checks via validator crate, format coverage with chrono/uuid, etc.). Each is a small isolated PR; staged for the next push.

I'll keep going — let me know if you want me to push further into the deferred set or pause here for review.

[lightsofapollo]

Final overnight push — 38 of 51 beads landed (≈ 75%)

10 commits on feat/conformance-3.1-3.2. cargo test --tests is 205/205 green; all 10 conformance fixtures pass at every active layer.

Latest commit batch

• H11 — Path Item $ref resolution against components/pathItems. The components/path-items-component.yaml fixture now flips to fully passing.
• J4-J8 — All JSON Schema 2020-12 keyword families typed on SchemaDetails:
  • prefixItems, contains, minContains, maxContains
  • patternProperties, propertyNames, unevaluatedProperties, unevaluatedItems
  • dependentRequired, dependentSchemas
  • contentEncoding, contentMediaType, contentSchema
  • if / then / else / not (conditional family)
  • Plus annotations: title, deprecated, readOnly/writeOnly, examples, example, $comment, $schema, $defs
  • should_use_dynamic_json was rewired to read these typed fields instead of doing string lookups in details.extra.

Cumulative status by phase

Phase	Done	Total	Outstanding
Phase 0 — Foundation	3	4	F3 (full MaybeRef<T> sum type — partially covered by ad-hoc reference: Option<String> fields)
Phase 1 — Top silent failures	11	15	T7 (non-JSON success bodies), T9 (success-path response headers), T12 (typed additionalProperties: <schema>), T14 (full RFC6570 style/explode matrix)
Phase 2 — 3.1 honesty	10	12	H3 (per-op security override emission), H12 (allOf-parent polymorphism + not codegen)
Phase 2b — JSON Schema 2020-12	6	10	J2 ($defs walking — typed but not enumerated yet), J3 (validator runtime checks), J9 (format → chrono::DateTime/uuid::Uuid/etc. — needs feature-gated deps), J10 ($self resolution)
Phase 3 — 3.2 deltas	8	10	D2 (in: "querystring" codegen), D6 ($self resolution per Appendix F)

What this looks like for users

A 3.1 spec that previously dropped fields silently now:

• Honors webhooks: and emits operation types from them
• Honors type: ["string", "null"] and produces Option<T>
• Honors header request parameters and sends them on the wire
• Distinguishes OPTIONS/HEAD/PATCH/TRACE from GET
• Percent-encodes path-template variables
• Surfaces summary/description/tags/deprecated into rustdoc
• Honors range status codes (2XX/4XX/5XX)
• Auto-detects SSE from text/event-stream responses
• Refuses unknown auth schemes loudly instead of silently rewriting to bearer
• Detects duplicate operationIds with a real error
• Resolves Path Item $ref against components/pathItems

A 3.2 spec additionally:

• Parses additionalOperations and query HTTP method, emits real client methods (reqwest::Method::from_bytes for custom verbs)
• Captures $self, Tag summary/parent/kind, Server name, Discriminator defaultMapping, MediaType itemSchema/prefixEncoding/itemEncoding
• Models OAuth deviceAuthorization flow + oauth2MetadataUrl
• Models SecurityScheme deprecated
• Models the new Components buckets: pathItems (3.1+) and mediaTypes (3.2)

Honesty surface: tests/conformance/status.toml has 33 entries — 22 supported, 6 partial, 5 unsupported. Each partial / unsupported still has a precise pointer to the remaining work.

What's left for a follow-up PR

The remaining 13 beads cluster into three coherent chunks:

1. Response-shape refactor — T7, T9 together. OperationInfo.response_schemas becomes a richer type that carries content-type + Rust target + headers. Unblocks typed non-JSON success bodies and success-path response headers.
2. Full RFC6570 parameter serialization (T14) — the largest single bead. Best done as its own PR with a wiremock test per (style, explode, in, type) combo.
3. Schema-keyword codegen (J2 walking, J3 validator-derived runtime checks, J9 chrono/uuid mapping, J10 $self/Appendix-F base-URI resolution). Each is small in isolation; they share the same area so could go in one PR.

Plus a few small ones: F3 (formal MaybeRef<T>), D2 (in: "querystring" codegen), H3/H12 (security AND/OR + allOf-parent polymorphism).

Branch is ready for review. cargo test --tests passes 205/205, conformance harness passes, no clippy regressions on what I edited.

[lightsofapollo]

Phase 4 — Generated client usability (5 new beads)

Once the spec corpus is mostly compiling (PR #18 ships 43 specs; followup branch shows 49), the next axis is whether the generated clients are pleasant to use. Filed five quality beads — picked from a longer list with the explicit framing "usability over prettiness".

ID	Title	What changes for users
Q1	Method-name canonicalization	client.get_file_metadata(id) instead of client.beta_get_file_metadata_v1_files_file_id_get(id). Heuristic strips path-segment-derived tail tokens + trailing HTTP verb.
Q2	Format-typed scalars	format: date-time → chrono::DateTime<Utc> (or time::OffsetDateTime); uuid → uuid::Uuid; byte → base64 bytes; binary → Bytes; ipv4/ipv6 → std::net::Ipv*Addr; uri → url::Url. Configurable, opt-in.
Q3	Builder pattern for ops with many params	Replace 25-arg method signatures (looking at you, OpenAI responses_create) with client.responses().create().model(...).max_tokens(...).send().await. Required path/headers stay positional; optional/body fields become builder setters.
Q4	Tagged discriminators	When the spec gives us discriminator: { propertyName, mapping }, emit #[serde(tag = "type")] enum instead of #[serde(untagged)]. Faster deserialization, cleaner JSON round-trip, and matches actual API wire format (Anthropic content blocks, OpenAI response items).
Q5	Display for ApiOpError that surfaces the typed body	Today the wall of JSON in the response body fills the message. Truncate to ~500 chars; prepend the typed variant name when typed.is_some(); surface parse-error reason when typed parsing failed. Full body still accessible via .body.

Acceptance criteria + file:line evidence for each are in tests/conformance/beads.yaml. Dependency map: Q3 depends on Q1 (better names → cleaner builder method names); the rest are independent.

These are deferred from the current PR (#18 / fix/spec-compile-corpus) so it can stay focused on getting the spec corpus to compile. Will pick them up after #18 lands.