Harden schema reference transformer for relative references

[captainsafia]

Addresses #59677, #58968, and #59427.

This PR resolves a set of issues that have been reported with schema reference resolution in the OpenAPI implementation. The crux of the issue deals with the way the underlying System.Text.Json generates relative references for schemas that include recursion or duplication.

For example, given the following type:

private class Root
{
    public Item Item1 { get; set; } = null!;
    public Item Item2 { get; set; } = null!;
}

private class Item
{
    public string[] Name { get; set; } = null!;
    public int value { get; set; }
}

The JsonSchemaExporter will produce the following schema:

{
  "type": "object",
  "properties": {
    "item1": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "string",
            "nullable": false,
            "format": null,
            "x-schema-id": null,
            "pattern": null
          },
          "nullable": true
        },
        "value": {
          "type": "integer",
          "pattern": null,
          "nullable": false,
          "format": "int32",
          "x-schema-id": null
        }
      },
      "x-schema-id": "Item",
      "nullable": true
    },
    "item2": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "$ref": "#/properties/item1/properties/name",
          "nullable": true
        },
        "value": {
          "type": "integer",
          "pattern": null,
          "nullable": false,
          "format": "int32",
          "x-schema-id": null
        }
      },
      "x-schema-id": "Item",
      "nullable": true
    }
  },
  "x-schema-id": "Root"
}

Where a relative reference to the first name schema in the Item1 property is used in the Item2 property. STJ anchors these references relative to the base type that was provided to the exporter, the Root type in this case. These relative references don't map to the OpenAPI document where the root for all schemas is the #/components/schemas entry.

To resolve this issue, we update the OpenAPI schema comparer to treat schemas where one schema uses a relative reference and the other does not as equivalent. In this case, the schemas for the item1 and item2 properties would be considered as equivalent since on contains a reference mapped to the other.

The current implementation is optimized to address the issue for when nested types are included directly in the referenced property. This PR expands the fix to address relative references that occur anywhere in the schema.

[mikekistler]

Looks good! 👍

[shkarface]

We also have a similar issue, when can we expect a fix to be released for this issue?

[captainsafia]

We also have a similar issue, when can we expect a fix to be released for this issue?

This PR will need to be approved and merged into main first before being back ported and going through the servicing process (ref). Release timelines vary depending on when the PRs to main and release/9.0 get merged so we'll know then.

[captainsafia]

/backport to release/9.0

[github-actions]

Started backporting to release/9.0: https://github.com/dotnet/aspnetcore/actions/runs/12677731301

[github-actions]

@captainsafia backporting to release/9.0 failed, the patch most likely resulted in conflicts:

$ git am --3way --empty=keep --ignore-whitespace --keep-non-patch changes.patch

Applying: Harden schema reference transformer for relative references
Using index info to reconstruct a base tree...
M	src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs
M	src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Transformers/Implementations/OpenApiSchemaReferenceTransformerTests.cs
Falling back to patching base and 3-way merge...
Auto-merging src/OpenApi/test/Microsoft.AspNetCore.OpenApi.Tests/Transformers/Implementations/OpenApiSchemaReferenceTransformerTests.cs
Auto-merging src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs
CONFLICT (content): Merge conflict in src/OpenApi/src/Services/Schemas/OpenApiSchemaService.cs
error: Failed to merge in the changes.
hint: Use 'git am --show-current-patch=diff' to see the failed patch
hint: When you have resolved this problem, run "git am --continue".
hint: If you prefer to skip this patch, run "git am --skip" instead.
hint: To restore the original branch and stop patching, run "git am --abort".
hint: Disable this message with "git config advice.mergeConflict false"
Patch failed at 0001 Harden schema reference transformer for relative references
Error: The process '/usr/bin/git' failed with exit code 128

Please backport manually!