Fix self-referential schema handling in collection schemas

[captainsafia]

Description

This PR expands relatives references in the schema generated by System.Text.Json since the Microsoft.OpenApi doesn't support resolving them correctly in v1.6. It also updates the comparison operators to handle relative references that are required for recursive types.

Fixes #60339

Customer Impact

Customer workarounds for this issue require post-processing on the document or changing the property order on types. These workarounds are hard to discover.

Regression?

• Yes
• No

Risk

• High
• Medium
• Low

Low risk becase:

• Change localized to M.A.OpenApi package.
• Tests written from multiple user reports.
• Changes introduced in this delta are easier to workaround for end-users.

Verification

• Manual (required)
• Automated

Packaging changes reviewed?

• Yes
• No
• N/A

[captainsafia]

We resolve the JSON pointer that this ref points to in the new code OpenApiSchemaService. We retain the $ref so that we can use it as a comparison shorthand in OpenApiSchemaComparer. Here, before we resolve all the schemas in the document, we remove the relative reference so that the schema can be inlined using the properties that were copied over.

[captainsafia]

Not having a schema ID indicates that the relative reference is to something that isn't a complex type, for example a List<string>. For things that have a schema ID, we create a ref to the schema in the OpenApiComponents via the OpenApiSchemaReferenceTransformer.

[captainsafia]

STJ will use different relative references for the same type depending on its entrypoint. This comparison helps us evaluate relative references with different structure that point to the same underlying property. For example, the schemas for ParentObject and List<ParentObject> differ like this:

using System.Text.Json.Nodes;
using System.Text.Json;
using System.Text.Json.Schema;
using System.Collections.Generic;
using System;

var schema1 = JsonSchemaExporter.GetJsonSchemaAsNode(JsonSerializerOptions.Web, typeof(ParentObject));
var schema2 = JsonSchemaExporter.GetJsonSchemaAsNode(JsonSerializerOptions.Web, typeof(List<ParentObject>));
Console.WriteLine(schema1.ToJsonString());
Console.WriteLine(schema2.ToJsonString());


public class ParentObject
{
	public int Id { get; set; }
	public List<ChildObject> Children { get; set; } = [];
}

public class ChildObject
{
	public int Id { get; set; }
	public required ParentObject Parent { get; set; }
}

ParentObject:

{
    "type": [
        "object",
        "null"
    ],
    "properties": {
        "id": {
            "type": [
                "string",
                "integer"
            ],
            "pattern": "^-?(?:0|[1-9]\\d*)$"
        },
        "children": {
            "type": [
                "array",
                "null"
            ],
            "items": {
                "type": [
                    "object",
                    "null"
                ],
                "properties": {
                    "id": {
                        "type": [
                            "string",
                            "integer"
                        ],
                        "pattern": "^-?(?:0|[1-9]\\d*)$"
                    },
                    "parent": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "properties": {
                            "id": {
                                "type": [
                                    "string",
                                    "integer"
                                ],
                                "pattern": "^-?(?:0|[1-9]\\d*)$"
                            },
                            "children": {
                                "$ref": "#/properties/children" // Same as below
                            }
                        }
                    }
                },
                "required": [
                    "parent"
                ]
            }
        }
    }
} 

List

{
    "type": [
        "array",
        "null"
    ],
    "items": {
        "type": [
            "object",
            "null"
        ],
        "properties": {
            "id": {
                "type": [
                    "string",
                    "integer"
                ],
                "pattern": "^-?(?:0|[1-9]\\d*)$"
            },
            "children": {
                "type": [
                    "array",
                    "null"
                ],
                "items": {
                    "type": [
                        "object",
                        "null"
                    ],
                    "properties": {
                        "id": {
                            "type": [
                                "string",
                                "integer"
                            ],
                            "pattern": "^-?(?:0|[1-9]\\d*)$"
                        },
                        "parent": {
                            "type": [
                                "object",
                                "null"
                            ],
                            "properties": {
                                "id": {
                                    "type": [
                                        "string",
                                        "integer"
                                    ],
                                    "pattern": "^-?(?:0|[1-9]\\d*)$"
                                },
                                "children": {
                                    "$ref": "#/items/properties/children" // This is the same as children not in a list
                                }
                            }
                        }
                    },
                    "required": [
                        "parent"
                    ]
                }
            }
        }
    }
}

[captainsafia]

We need to override just the ref keyword so we can keep the other transformations that happened before this LoC intact (like setting the x-schema-id property).

[captainsafia]

@BrennanConroy Added snapshot tests and put in explainers next to each code delta. Ready for review!

[dotnet-policy-service]

Hi @captainsafia. Please make sure you've updated the PR description to use the Shiproom Template. Also, make sure this PR is not marked as a draft and is ready-to-merge.

To learn more about how to prepare a servicing PR click here.

[BrennanConroy]

Are there relevant/similar tests for all these in main?

[BrennanConroy]

This compiles into 2 substring calls, should use span comparison.