feat: find and fix every schema that degrades to serde_json::Value (#62, #65)

[lightsofapollo]

Summary

serde_json::Value in generated code means one of two things: the schema
declared an unconstrained value, or the generator dropped type information the
schema carried. Nothing distinguished them, so nobody could say which of the
corpus's untyped fields were defects.

This adds the instrument, then uses it. Corpus-wide recoverable untyped fields
go from 3,347 to zero.

The instrument

SchemaType::Untyped { shape, reason } carries the reason in the IR, so the
census is derived from the types that actually get generated rather than
recorded as analysis runs — a schema referenced by fifty properties counts fifty
times, and a pruned one counts zero. (Recording on the side got both wrong, by
47%.)

$ openapi-to-rust generate api.yaml --report-untyped
untyped: 46 field(s), 0 of them recoverable
    44  UntypedAdditionalProperties  faithful   e.g. AssistantMessageRequest.<additionalProperties>
     1  AnySchema                    faithful   e.g. TcpWarmingV1TcpWarmingGetResponse
     1  OpaqueObject                 faithful   e.g. JSONSchema.schema

scripts/untyped-census.sh runs it over the corpus and rewrites
tests/conformance/untyped-report.md, so a typing change shows its delta in
review; --check fails when the baseline is stale.

A normalization pass reports anything that reaches the IR still stringly-typed
as Unclassified — a visible gap in the taxonomy rather than a missing count.
The corpus has none.

What it found, and what this fixes

Cause	Before	Now
inline-union-dropped	2,182	0
unrepresentable-union	592	0
inline-object-dropped	342	0
inline-composition-dropped	102	0
unrepresentable-composition	55	0
inline-enum-dropped	51	0
unresolved-reference	15	0
unsupported-type-keyword	8	0

Two root causes dominated:

• One idiom. OData spells a nullable reference
  anyOf: [$ref, {type: object, nullable: true}], and reading the second branch
  literally makes the union unrepresentable, costing the first branch its type:
  2,127 fields in Microsoft Graph alone. Those become Option<T>.
• One structural gap. A struct field can hold a primitive, a reference, an
  array, or a tuple; an inline object, union, enum, or merged allOf has to be
  generated as its own item. Analysis understood those schemas and left them in
  field positions, where the generator emitted serde_json::Value. They are now
  hoisted to named types — in property, array-element, and tuple-element
  positions alike.

The rest were narrower gaps, each traced to a real document: single-member
allOf (Box), allOf inside array items (Asana), $ref to any local JSON
Pointer (PagerDuty), type: null → () (Discord), oneOf: [] beside a real
type (Discord), single-branch unions (gcore), branches differing only in
pattern/format (Runway, gcore), branches that only alternate required
(Cloudflare), and pointer branches expanded before the union is built
(PagerDuty).

Where I deliberately stopped narrowing

{type: object, nullable: true} is read as a null marker only beside a
$ref. Read literally it also says "or any object", and 33 corpus fields are
anyOf: [{type: string, nullable: true}, {type: object, nullable: true}] where
the objects are real — typing those as Option<String> would compile and then
fail on a payload the schema allows. Microsoft Graph keeps all 2,127 of its
narrowings; those 33 stay serde_json::Value and are reported as faithful.

The last shape standing was a base object combined with a variant union —
{properties: {...}, anyOf: [A, B]}, "these fields, and one of these shapes".
Reading only the union loses the fields and reading only the object loses the
alternatives, so the generator did neither. It now generates the struct with the
union in a #[serde(flatten)] field, and both halves round-trip byte-identically
(verified against a compiled scratch crate, since flatten has sharp edges).
That closes #65.

Generated compatibility

• Generated model or method signatures: substantially, and that is the
  point. 4,404 fields across the corpus move from serde_json::Value to a
  real type. Consumers of those fields will need to update; the wire format is
  unchanged.
• Query/path/header/body wire behavior: unchanged. serde reads and writes the
  narrowed types identically — Option<T> for a nullable reference, () for
  type: null (which is null on the wire), tuples as arrays.
• Generated runtime dependencies or features: none. Extensible enums now
  implement Display/AsRef<str> and expose as_str, matching what generated
  string enums already had — needed because a multipart field can now be an
  enum.
• Configuration defaults or migrations: none.
• Remaining unsupported OpenAPI shapes: boolean subschemas outside items
  (Boolean subschemas (true/false) fail to parse outside items #63). Everything the census can attribute is now typed.

Validation

• Added or updated a focused fixture and behavioral regression test.
  tests/recoverable_typing_test.rs covers every pattern above, each naming
  the spec it came from, asserting both the generated type and that the
  census no longer reports the field. Negative cases are pinned as hard as
  positive ones: a nullable branch that constrains something stays a union,
  a nullable object beside a scalar is read literally, and an unconstrained
  schema stays serde_json::Value. tests/untyped_census_test.rs covers the
  taxonomy; tests/untyped_report_cli_test.rs covers the CLI surface.
• Reviewed every changed snapshot; no unrelated churn. Four show the new
  enum surface, one now includes a struct that was previously referenced by
  a union variant and never generated, and two differ only in item order,
  which the dependency edges changed.
• cargo fmt --check
• cargo clippy --all-features -- -D warnings
• cargo test --all-features
• RUSTDOCFLAGS=-Dwarnings cargo doc --no-deps --all-features
• Ran scripts/install-smoke.sh for packaging/dependency changes.
• Ran a targeted or full scripts/spec-compile.sh for generator changes
  (full corpus).
• Updated README, rustdoc, or changelog for user-visible behavior.

The corpus gate earned its keep repeatedly here. Typing these fields exposed
three latent problems it caught and this branch fixes: a hoisted union that
declared no dependencies made a reference cycle invisible to recursion detection
(Stripe generated an infinitely-sized enum); extensible enums lacked the
Display that multipart form fields render through (OpenAI stopped compiling);
and a struct that flattens a variant can derive neither Default nor a request
builder, since both would have to invent a variant (Cloudflare, GitHub,
LaunchDarkly, Lithic).

Notes for reviewers

Smallest useful review path: UntypedReason and SchemaType::renders_inline
in src/analysis.rs (the taxonomy and the capability it mirrors), then
hoist_inline_property_type (the structural fix), then non_null_variant in
src/openapi.rs (the narrowing, and its limit).

🤖 Generated with Claude Code

https://claude.ai/code/session_01TD3TSeWKu4VqLtEnRMDjry

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
openapi-to-rust	Ready	Preview	Aug 27, 2026 6:06am