Skip to content

fix(macro): request-only types keep their name; typed codec fields in request views - #381

Open
owjs3901 wants to merge 9 commits into
mainfrom
owjs3901/request-view-naming
Open

owjs3901 wants to merge 9 commits into
mainfrom
owjs3901/request-view-naming

Conversation

@owjs3901

@owjs3901 owjs3901 commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Two owner-decided changes to the 0.8 FastAPI-style request views ({Name}Input):

  1. Request-only types keep their name. A type whose request view differs gets {Name} + {Name}Input only when a response reaches its response view too (directly or through another type). When only request bodies reach it, the request view is emitted under {Name}, request bodies reference {Name}, and no orphan response view is left behind. Response-only types and types used on both sides behave as before. The collision naming ({Name}Input2, …) is unchanged.

    • Implemented as a post-pass (component_schemas::collapse_request_only_inputs) after the paths are built. The response side is every $ref a path reaches outside its request parameters / bodies, plus every component the request side does not reach (an unused documented type keeps the response views it references). The {Name} views being replaced are excluded from those roots, so the transitive request-only case (CreateOrder { items: Vec<LineItem> }) collapses both types. Generic instances (Tree_i32.Input → Tree_i32) are handled the same way.
  2. Codec fields are typed in request views. A field read by a custom serde function (deserialize_with / with) is documented from its Rust type (or #[schema(value_type)]) in the request view, instead of an untyped {}. Option<Option<T>> becomes a nullable T, and #[serde(default)] still makes the field optional. A deserialize_with alone no longer splits the views. Fields written by with / serialize_with still document {} in responses.

  3. Response views follow what serde writes. An Option<T> field is required in the response view with a nullable type (serde writes null for None); only skip_serializing_if leaves it optional. A skip_serializing field is absent from the response view, where it used to be an optional writeOnly property. Request views keep Option<T> optional, so a type with Option fields that is read and returned now gets a {Name}Input (in axum-example: CreateUserWithMetaInput, GardeProfileInput, InternallyTaggedMessageInput, JsonPayloadsInput). Generated clients change from bio?: string | null to bio: string | null for responses. An Option with skip_serializing_if = "Option::is_none" (what serde_with's #[skip_serializing_none] adds) is never written as null, so its response property is optional and not nullable (email?: string); Option<Option<T>> keeps the inner null, other predicates keep the nullable type, request views still accept null. Verified at runtime in axum-example/tests/integration_schema.rs (response_schema_matches_the_serialized_body: real axum Json body vs schema!).

Before / after: a request-only PortfolioUpdateRequest

#[serde(rename_all = "camelCase")]
pub struct PortfolioUpdateRequest {
    #[serde(default)] pub title: String,
    #[serde(default, deserialize_with = "deserialize_optional_field")]
    pub production_end_date: Option<Option<NaiveDate>>,
}
// async fn update(Json(r): Json<PortfolioUpdateRequest>) -> Json<Portfolio>

Before (0.8.0): the request body references PortfolioUpdateRequestInput, and PortfolioUpdateRequest is an orphan:

"PortfolioUpdateRequest": { "properties": { "productionEndDate": { "default": null, "format": "date", "type": ["string","null"] }, "title": { "default": "", "type": "string" } }, "required": ["title"], "type": "object" },
"PortfolioUpdateRequestInput": { "properties": { "productionEndDate": { "default": null, "description": "Converted by a custom serde function (`with` / `serialize_with` / `deserialize_with`); its wire shape is not known. Add `#[schema(value_type = T)]` to document it." }, "title": { "default": "", "type": "string" } }, "type": "object" }

After: the request body references PortfolioUpdateRequest, and it is the only component:

"PortfolioUpdateRequest": { "properties": { "productionEndDate": { "default": null, "format": "date", "type": ["string","null"] }, "title": { "default": "", "type": "string" } }, "type": "object" }

Intentionally changed existing tests / snapshots

  • tests_accuracy::identical_or_unused_request_views_emit_nothing: Holder / Opt are request-only, so they are now emitted as Holder / Opt (request views) rather than Holder, HolderInput, Opt, OptInput. The test now also checks the request-body $ref and that Opt.x is optional.

  • request_view::tests::direct_differences::with_both_sides changes false → true: with hides the response shape while the request view is typed. New cases cover deserialize_with alone and tuple deserialize_with (both false).

  • Snapshots where a deserialize_with / with field (named, tuple position, path / query parameter) was {} in the request view now show its Rust type: wire_override_field_deserialize_with_on_deserialize, wire_override_field_with_unknown, wire_override_transparent_with, struct_views_tuple_codecs, enum_views_tuple_variant_fields, enum_views_variant_codec_untagged (field positions only; variant-level codecs are unchanged), path_wire_override_fields, query_wire_override_fields, request_shapes_custom_deserializer_option.

  • examples/axum-example: openapi.json / integration_test__openapi.snap drop five request-only *Input components (AdvancedSearchRequest, CreateUuidItemRequest, Pagination, UpdateConfigRequest, UserListRequest). In codecs_component_EventTimesInput, checksum (with = "hex") is now documented as its Rust type in the request view.

  • Item 3: struct_schema/tests.rs (Option required in responses; skip_serializing dropped), schema_macro/codegen.rs (same, via schema!), request_view/tests.rs (plain split into plain / option / option_skip_if), tests_accuracy (the Same fixture gains skip_serializing_if so it stays identical in both views), crates/vespera/tests/schema_round5.rs and axum-example/tests/integration_schema.rs (schema! is the response view), 17 macro snapshots + example snapshots, and e2e/devup-api/src/calls.ts (the request type is now GardeProfileInput).

  • Option::is_none rule: serde_attrs/codec.rs (skips_none_on_output cases), struct_schema/tests_option_output.rs (new), request_view/tests.rs (skip_serializing_if_option now differs), 2 enum snapshots, SkipResponse.email4 in the example openapi.json.

Trade-offs worth a look

  • A with = "ts_seconds" / with = "hex" field without value_type is now documented in requests as the Rust type, not its real wire shape (date-time string instead of an integer; a byte array instead of a hex string). This follows the owner's "document from the Rust type" rule; value_type remains the fix. A with field on a type used on both sides now also produces a {Name}Input, because the response is {} and the request is typed.
  • vespera!(merge = [...]) merges components first-wins. If a child app uses Foo only as a request body while the parent returns Foo, both now name their component Foo, and one of the two views is dropped. Before, they were FooInput and Foo.

New tests: openapi_generator/tests_request_only.rs covers a request-only type with no orphan, a response-only type, a type used on both sides, the transitive CreateOrder/LineItem cases (request-only, LineItem also returned, both returned), an unused type keeping a referenced response view, UserInput2 collision naming on both sides vs. request-only, the request-only recursive generic instance, and the Option<Option<NaiveDate>> + deserialize_with schema.

Checks run locally (Windows)

  • cargo test --workspace --no-fail-fast ✅
  • bun run lint (both clippy sets with -D warnings, cargo fmt --check, oxlint) ✅
  • RUSTDOCFLAGS=-D warnings cargo doc --workspace --no-deps --all-features ✅, cargo test --workspace --doc ✅
  • bun test ✅, bun scripts/check-version-alignment.ts ✅
  • cargo tarpaulin -p vespera_macro --engine llvm with CI's rustfmt layout: every changed line covered. Four untouched pre-existing loop-body lines show as uncovered only in this Windows run. CI's Linux workspace-wide gate is the authority.

🤖 Generated with Claude Code

owjs3901 and others added 9 commits November 17, 2026 14:11
… request views

A type whose request view differs gets a separate `{Name}Input` only when
its response view is also used. When request bodies reach `{Name}Input`
but nothing outside the request side reaches `{Name}`, the request view
takes over `{Name}` and every `$ref` follows (generic `Tree_i32.Input`
alike), so request-only DTOs keep their names and no orphan response view
is emitted.

Fields read by a custom serde function (`deserialize_with` / `with`) are
documented from their Rust type (or `value_type`) in request views instead
of an untyped `{}`; a `deserialize_with` alone no longer splits the views.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-expression .Input scan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…izing fields

serde always writes an Option field (null for None), so the response view
requires it with a nullable type; only skip_serializing_if leaves a key out.
A skip_serializing field is never written, so it is absent from the
response view instead of an optional writeOnly property. Request views keep
Option fields optional, so a type with Option fields read and returned gets
a {Name}Input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… Option rule

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A None is sent as null (required, nullable), a skip_serializing_if None is
left out (not required), a skip_serializing field is never sent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…esponses

serde never writes null for a field with skip_serializing_if =
"Option::is_none" (serde_with's #[skip_serializing_none] adds exactly
that), so the response view documents the Some value: optional and not
nullable. Option<Option<T>> keeps the inner null (Some(None) is written as
null); other predicates keep the nullable type. Request views still accept
null.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An Option skipped by Option::is_none now differs between views, so the
fixture that exercises dropping an identical input uses a plain field.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…-naming

# Conflicts:
#	examples/axum-example/tests/snapshots/integration_test__openapi.snap

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant