Follow-up (#223): body-bound shared DTO ([FromBody]/[FromForm]) may not receive rules when the same type is flattened as [FromQuery]

[avgalex]

Follow-up split out from the review of #224 (fix for #223): #224 (comment)

Limitation

The #223 fix recovers a concrete schema for a "reserved-but-removed" [FromQuery] container type by generating it into a throwaway SchemaRepository (SwashbuckleSchemaProvider.GetSchemaForType). That is safe for the parameters path, because there the recovered container schema is only used to read constraint values, which are then copied field-by-field onto the real operationParameter.Schema (FluentValidationOperationFilter.ApplyRulesToParameters).

The request-body path is different. In FluentValidationOperationFilter.ApplyRulesToRequestBody (around FluentValidationOperationFilter.cs:464), when schemaRefId != null it does:

resolvedSchema = schemaProvider.GetSchemaForType(parameterType);
...
FluentValidationSchemaBuilder.ApplyRulesToSchema(schema: resolvedSchema, ...); // mutates resolvedSchema in place

Here the recovered schema is the mutation target — there is no copy-back onto a separate document object. If the recovered schema came from the throwaway fallback, any rules applied to it are written to a disposable object and never reach the emitted document.

When this can bite

Only when a single DTO type is used both:

• as a flattened [FromQuery]/[AsParameters] container (whose component is removed by the Issue Validators for records used with [AsParameters] create unused component schemas #180 cleanup, leaving the type reserved-but-removed), and
• as a [FromBody]/[FromForm] body in the same document,

with RemoveUnusedQuerySchemas = true, and with the query operation processed before the body operation (so the reserved-but-removed state is in effect when the body operation runs).

Not a regression

This path already skipped in this situation before #224 — the empty-Properties guard (resolvedSchema.Properties.Count == 0) short-circuited it. #224 did not change body-bound behavior; it deliberately scoped itself to the "container schema used only for reading constraints" pattern (parameters). So this is a pre-existing gap, surfaced by the review, not something #224 introduced.

Needs a concrete repro to confirm how realistic the mixed [FromQuery] + [FromBody] shared-type scenario is in practice.

Fix direction

The structural fix is "Variant B" from the #223 discussion: make FluentValidationDocumentFilter production-ready and promote it (it is currently Experimental, behind RegistrationOptions.ExperimentalUseDocumentFilter). A document filter batches all types/parameters across the whole document and performs the Issue #180 cleanup once at the end, so the per-operation reserved-but-removed state never arises for any binding source — bodies included. That closes this class of bug uniformly instead of per-path.

Its parity checklist (from the #223 notes): required marking (#209), request bodies + [FromForm] + encoding.contentType (#216), full component-schema coverage (response DTOs, nested SetValidator), and robustness fixes (FindParam only inspects the first operation of a path; duplicate schemasForParameters; nullability/obsolete cleanup).

Status

Filing to track; no action pending on #224 (which stays scoped to #223). Would like feedback on whether the mixed body+query shared-DTO scenario is worth prioritizing on its own, or folded into the Variant B effort.

[avgalex]

Interim fix direction for net10.0: SchemaRepository.ReplaceSchemaId

Suggested by @jgarciadelanoceda in #224 (comment): Swashbuckle 10.1.0 added a public SchemaRepository.ReplaceSchemaId(Type, string) (domaindrivendev/Swashbuckle.AspNetCore#3708). It moves the schema to a new key in Schemas and removes the type from the private _reservedIds map — exactly the half of the state that public API could not reach before.

How it applies here

Change the Issue #180 cleanup in FluentValidationOperationFilter.ApplyRulesToParameters to heal the repository state instead of leaving the type reserved-but-removed:

// track container types whose schemas were generated as a side effect, then at cleanup:
if (repository.ReplaceSchemaId(containerType, tempId)) // clears the reservation; must run BEFORE removal
    repository.Schemas.Remove(tempId);                  // repository state is now fully consistent

With the reservation cleared, the next operation sharing the DTO regenerates a full concrete schema into the shared repository. Consequences:

• The When one or more endpoints have the same Dto the firts one gets the FluentValidationRule and the next ones are not getting it #223 desync never arises (prevention instead of the throwaway-repository compensation from fix(#223): apply FluentValidation rules to every endpoint sharing a [FromQuery] DTO #224).
• The body-bound path tracked by this issue is fixed on net10.0: GetSchemaForType finds a real component in the shared repository, so ApplyRulesToRequestBody mutates the actual document object.
• Removes a latent hazard: in the reserved-but-removed state, a later [FromBody]/response usage of the same type emits a $ref to a component that no longer exists (dangling reference in the emitted document). Note RemoveUnusedQuerySchemas defaults to true, so this state is reachable with default settings.
• Removes the per-parameter regeneration overhead noted in the fix(#223): apply FluentValidation rules to every endpoint sharing a [FromQuery] DTO #224 review.

Constraints

• Versions: ReplaceSchemaId shipped in Swashbuckle 10.1.0. Our net10.0 target pins 10.2.1 (available); net8.0/net9.0 pin 8.1.1 (not available). Bumping the minimum for older TFMs would force consumers through the Microsoft.OpenApi 2.x breaking change — not acceptable. So this is an OPENAPI_V2-only improvement; the fix(#223): apply FluentValidation rules to every endpoint sharing a [FromQuery] DTO #224 throwaway fallback remains the baseline for net8.0/net9.0.
• Nested types: GenerateSchema also creates components for nested complex types as a side effect; their reservations dangle the same way. ReplaceSchemaId needs the Type, which is only known for the root container (unless we walk the property graph). The throwaway fallback in SwashbuckleSchemaProvider.GetSchemaForType stays as a safety net for those.

Relation to Variant B

Variant B (promoting FluentValidationDocumentFilter) remains the structural fix: the document filter performs the cleanup once at the end of the whole document, so per-operation desync cannot occur for any binding source. The ReplaceSchemaId cleanup is an incremental hardening of the operation-filter path that ships value on net10.0 without waiting for the Variant B parity checklist.