7.1.2 replaces schema reference with copy of schema

[natehitze-eventlink]

After an upgrade I was trying to debug why our OpenAPI document changed in a way that prevented tools from knowing which classes were nested. It's easier to explain with an example.

Packages:

<PackageReference Include="FluentValidation.AspNetCore" Version="11.3.1" />
<PackageReference Include="MicroElements.Swashbuckle.FluentValidation" Version="7.1.2" />
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="10.0.5"/>
<PackageReference Include="Swashbuckle.AspNetCore" Version="10.1.5" />

Here's the Program.cs:

using FluentValidation;
using FluentValidation.AspNetCore;
using MicroElements.Swashbuckle.FluentValidation.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddFluentValidationAutoValidation();
builder.Services.AddValidatorsFromAssemblyContaining<Program>();
builder.Services.AddControllers();
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddFluentValidationRulesToSwagger();
builder.Services.AddSwaggerGen();

var app = builder.Build();
app.UseSwagger();
app.MapGet("/getperson", () => new Person());
app.Run();

public class Person
{
    public Address Address { get; set; }
}

public class PersonValidator : AbstractValidator<Person>
{
    public PersonValidator()
    {
        RuleFor(x => x.Address)
            .NotEmpty()
            .SetValidator(new AddressValidator());
    }
}

public class Address
{
    public string Street { get; set; }
}

public class AddressValidator : AbstractValidator<Address>
{
    public AddressValidator()
    {
        RuleFor(x => x.Street).NotEmpty();
    }   
}

On 7.1.2 you get this document:

{
  "openapi": "3.0.4",
  "info": {
    "title": "ReproWeb",
    "version": "1.0"
  },
  "paths": {
    "/getperson": {
      "get": {
        "tags": [
          "ReproWeb"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Address": {
        "required": [
          "street"
        ],
        "type": "object",
        "properties": {
          "street": {
            "minLength": 1,
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Person": {
        "required": [
          "address"
        ],
        "type": "object",
        "properties": {
          "address": {
            "required": [
              "street"
            ],
            "type": "object",
            "properties": {
              "street": {
                "minLength": 1,
                "type": "string"
              }
            },
            "additionalProperties": false
          }
        },
        "additionalProperties": false
      }
    }
  },
  "tags": [
    {
      "name": "ReproWeb"
    }
  ]
}

components.schemas['Person'].properties['address'] is a full object.

In 7.1.1 you get this:

{
  "openapi": "3.0.4",
  "info": {
    "title": "ReproWeb",
    "version": "1.0"
  },
  "paths": {
    "/getperson": {
      "get": {
        "tags": [
          "ReproWeb"
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Person"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Address": {
        "required": [
          "street"
        ],
        "type": "object",
        "properties": {
          "street": {
            "minLength": 1,
            "type": "string"
          }
        },
        "additionalProperties": false
      },
      "Person": {
        "required": [
          "address"
        ],
        "type": "object",
        "properties": {
          "address": {
            "$ref": "#/components/schemas/Address"
          }
        },
        "additionalProperties": false
      }
    }
  },
  "tags": [
    {
      "name": "ReproWeb"
    }
  ]
}

where components.schemas['Person'].properties['address'] is back to being a $ref object.

[avgalex]

This has been fixed in v7.1.3. The NuGet package should be available shortly.

[avgalex]

Root cause: In v7.1.2, ResolveRefProperty was introduced to fix BigInteger shared schema mutation (Issue #146). It created a shallow copy of the referenced schema and replaced the $ref in the parent's Properties dictionary with the inline copy. This worked for BigInteger constraints but had an unintended side effect — all $ref properties (including nested object types like Address) were replaced with full inline copies, destroying the reference structure in the OpenAPI document.

Fix: Before applying validation rules, we now snapshot all $ref properties. After rules are applied, we compare the inline copy against the original component schema. If no validation constraints were added (min/max, minLength, pattern, format, etc.), the original $ref is restored. Properties that were actually modified by rules (like BigInteger with per-model min/max) keep their inline copies as expected.

[natehitze-eventlink]

7.1.3 is working for us. Thanks for the quick fix!

[jrgcubano]

@avgalex I'm using version 7.1.4 and has broken the schema for many of the validators we have..

I would appreciate any advice on how to proceed.

Example:

 public class CreateUserRequest
 {
     public CreateUserParams User { get; set; }
 }

 public class CreateUserParams
 {
     public string Email { get; set; }
     public string Name { get; set; }
 }

 public class CreateUserRequestValidator : AbstractValidator<CreateUserRequest>
 {
     public CreateUserRequestValidator()
     {
         RuleFor(a => a.User).NotEmpty().SetValidator(new CreateUserParamsValidator());
     }
 }

 public class CreateUserParamsValidator : AbstractValidator<CreateUserParams>
 {
     public CreateUserParamsValidator()
     {
         RuleFor(a => a.Email).NotEmpty().EmailAddress();
         RuleFor(a => a.Name).NotEmpty().MaximumLength(510);
     }
 }

Output:

 components.schemas.CreateUserRequest:
 {
   "required": ["user"],
   "type": "object",
   "properties": {
     "user": {
       "type": "object",
       "required": ["email", "name"],
       "properties": {
         "email": { "minLength": 1, "type": "string", "format": "email" },
         "name":  { "minLength": 1, "maxLength": 510, "type": "string" }
       }
     }
   }
 }

 components.schemas.CreateUserParams (orphan — $ref count = 0 anywhere in the document):
 {
   "required": ["email", "name"],
   "type": "object",
   "properties": {
     "email": { "minLength": 1, "type": "string", "format": "email" },
     "name":  { "minLength": 1, "maxLength": 510, "type": "string" }
   }
 }

Expected:

 CreateUserRequest.user becomes { "$ref": "#/components/schemas/CreateUserParams" } ...

Thanks in advance for your help.

[avgalex]

@jrgcubano thanks for the detailed report. A couple of questions to help us pin this down:

1. Which version was the last one that produced the correct output (user rendered as { "$ref": "#/components/schemas/CreateUserParams" })? In particular — did 7.1.3 work for these validators and the regression appeared only after upgrading to 7.1.4, or was it already broken on 7.1.3?

2. Could you confirm the exact package versions: MicroElements.Swashbuckle.FluentValidation, Swashbuckle.AspNetCore, Microsoft.AspNetCore.OpenApi, FluentValidation(.AspNetCore)?

For context: the $ref-preservation fix for #198 (including a regression test for SetValidator on a nested object) shipped in 7.1.3 and is still present in 7.1.4 and the current 7.1.5-beta.

I built a project from your exact Program.cs and validators (net10.0, Swashbuckle.AspNetCore 10.1.5, Microsoft.AspNetCore.OpenApi 10.0.x, FluentValidation.AspNetCore 11.3.1) against the current code, and the generated document is the expected one:

"CreateUserRequest": {
  "required": [ "user" ],
  "type": "object",
  "properties": {
    "user": { "$ref": "#/components/schemas/CreateUserParams" }
  },
  "additionalProperties": false
}

CreateUserParams stays a proper component (not orphaned) and keeps its email/name constraints. So I can't reproduce the inline-copy behavior with the snippet above.

A minimal runnable repro (a tiny project that shows the orphaned schema), or at least the precise versions/setup, would really help us see what's different on your side. Thanks!

[avgalex]

Update: I found a path that reproduces exactly what you're seeing (inline copy of the nested object + an orphaned child component), and there's a fix in #206 (targeting 7.1.6-beta).

Trigger: it's not SetValidator(new XxxValidator()) — that path keeps the $ref. It reproduces when the nested object's constraints come from ChildRules(...) (or any inline child validator), i.e. the child type has no standalone validator class:

RuleFor(a => a.User)
    .NotEmpty()
    .ChildRules(u =>
    {
        u.RuleFor(c => c.Email).NotEmpty().EmailAddress();
        u.RuleFor(c => c.Name).NotEmpty().MaximumLength(510);
    });

That produces exactly your output: User inlined, CreateUserParams orphaned.

Why: with no standalone child validator, the child component schema is generated empty and gains its required only after the parent's inline $ref snapshot was taken; the stale required then diverged and defeated the 7.1.3 ref-restore check. #206 makes that comparison directional so the $ref is restored.

Could you confirm whether your real validators use ChildRules / an inline InlineValidator for the nested type (rather than a separate CreateUserParamsValidator class)? That would confirm we've nailed your case.

Workaround until 7.1.6-beta ships: extract the inline rules into a standalone validator class and use SetValidator(new CreateUserParamsValidator()) — that path already preserves the $ref.