[hardbyte]

Another step towards #129, following #211. It picks up the review comment on #210:

The wire-to-JSON-Schema rules now exist twice. … Under the #129 direction, though, the variant shapes (unit/newtype/tuple/struct) should come from shared code next to #204's Layout, so both generators read the same facts.

How a variant appears on the wire follows from its shape in serde's data model and its enum's representation. OpenAPI, Python and the shared layout each worked out the shape from Fields themselves, and #210 added another copy for Python's JSON schemas. This PR defines it once, and every place in OpenAPI and Python that decides a shape now reads it.

The shape

codegen/schema/shape.rs, next to layout.rs:

Shape	Fields	Externally tagged wire
Unit	none	"A"
Newtype(&Field)	one unnamed	{"A": T}
Tuple(&[Field])	any other number of unnamed, including A()	{"A": [T, U]} / {"A": []}
Struct(&[Field])	named, including A {}	{"A": {...}} / {"A": {}}

Shape::of(&Fields) classifies; Shape::fields() lists the fields in order.

Now read from it

OpenAPI. variant_to_schema matches on Shape for every representation (external, adjacent, internal, untagged), replacing its Fields matches and fields.len() == 1 && !fields[0].is_named() checks.

Layout. The variants of an internally tagged enum.

Python (second commit for everything after the first item):

• The externally tagged renderer. The (wire_name, shape) entries fix(python): describe the wire shape in JSON schemas of tagged and flattened enums #210 passes to the runtime's externally_tagged_json_schema come from Shape through one mapping, json_schema_shape, instead of a string written in each branch.
• The other enum renderers: adjacently tagged, internally tagged and untagged.
• Flattened enums:
  • the variants of a struct's flattened internally tagged enum
  • variant_flattened_groups
  • fix(python): describe the wire shape in JSON schemas of tagged and flattened enums #210's unit-only check for a flattened externally tagged enum
• render_enum's complex-variant check, which keeps counting an empty tuple variant A() as a unit (see below).
• enum_unit_tag_set.
• The newtype-struct checks in render_struct and type_ref_to_python_type. Struct::is_tuple() && fields.len() == 1 and Shape::Newtype agree on any schema whose unnamed fields are named by index, which reflection always produces.

What still matches Fields in Python only visits every field whatever its shape, or builds one:

• collect_type_vars_from_type
• validate_type_references
• rename_type_params_in_type
• infer_enum_generic_params
• concrete_struct_from_type_ref
• materialize_nested_policy_flatten

Shape adds nothing there; fields.iter() would be the tidy-up.

Output

Generated output is unchanged. Two existing quirks are kept on purpose, because fixing either changes output and belongs in its own PR:

• OpenAPI: an empty externally tagged variant (B {}, C()) leaves its key out of required, although serde always writes it.
• Python: render_enum counts A() as a unit, so enum E { A, B() } becomes a string enum with B = "B". Serde writes B() as {"B": []}, so the generated client can't read that variant.

Testing

• Generated output. I generated the demo client (Python, TypeScript, Rust) and the codegen coverage, enum compatibility and field presence fixtures on main (53f50d1) and on this branch, after each commit. All 60 files are byte-identical, including fix(python): describe the wire shape in JSON schemas of tagged and flattened enums #210's serde samples.
• Snapshots. No snapshot changed. They cover the paths changed here, including:
  • empty, newtype and untagged variants in OpenAPI
  • tuple[()] and root: None for untagged enums
  • adjacently tagged tuple content
  • flattened internally tagged variants
• New tests:
  • Shape: a newtype vs a tuple (including A()), empty and non-empty structs, field order
  • the Python error for an internally tagged tuple variant, which also passes on main, so the message is unchanged
• Passing locally:
  • cargo fmt --check, clippy -D warnings --all-targets, and cargo test --workspace --all-features: 368 passed
  • every Python codegen smoke step, on 3.14 and on 3.12 with pydantic 2.10.0, including fix(python): describe the wire shape in JSON schemas of tagged and flattened enums #210's "JSON schemas against serde samples". This ran on the first commit; the second leaves generated output byte-identical.

Not changed

• TypeScript still classifies Fields itself, in about 13 places; separate PR.
• Mapping a shape to JSON Schema still exists twice: in openapi.rs, and in the runtime's serde.py, which rebuilds it from Pydantic's core schema. Removing that duplication would mean codegen emitting the schema fragments itself, which is a separate decision.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VjkNsfHSd5osRevK95McpQ

[github-actions]

📖 Documentation Preview: https://reflectapi-docs-preview-pr-212.partly.workers.dev

Updated automatically from commit 09d54d4

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review for a one-time review, or @claude review always to subscribe this PR to a review on every future push.

_{Tip: disable this comment in your organization's Code Review settings.}

[hardbyte]

@claude review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T02:57:15.862885Z	057921b	Draft marked ready

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Code review found no issues

No high-confidence issues detected in this change.