Add wrapper type over JSON schema provided by System.Text.Json

[captainsafia]

In .NET 9, the System.Text.Json team will embark on adding support for JSON schema to its libraries (see dotnet/runtime#100159). The support consists of three aspects:

• Expanding the type info resolver APIs to provide more metadata when generating JSON schemas
• Adding support for generating schemas from .NET types according to the serialization contracts
• Providing an exchange type to represent JSON schemas

As of .NET 9, the intent is to provide an "opaque" type to represent JSON schemas in the document. This type would not provide explicit APIs for retrieving different properties within the JSON schema and would allow the schema generator to evolve as needed to meet the requirements of the spec.

To provide a uniform experience for users interacting with OpenAPI schemas across different versions of Microsoft.OpenApi, it's necessary to ship a "shim" type that allows us to take advantage of the schema generation provided by the platform, enhance it with OpenAPI-specific information, and map it to a strongly-typed API.

The shim type would be implemented as follows:

[JsonConverter(typeof(JsonConverter))]
internal sealed class OpenApiJsonSchema(OpenApiSchema schema)
{
	public OpenApiSchema Schema { get; } = schema;

	internal sealed class JsonConverter : JsonConverter<OpenApiJsonSchema>
    {
		public override OpenApiJsonSchema? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
		{
			// Use the `Utf8JsonReader` to parse out the opaque type provided by the platform into an
			// OpenApiSchema to be initialized in the platform.
		}
	}
}

The example above shows implementing this shim type as a bridge between the opaque type provided by the platform and the OpenApiSchema type available in Microsoft.OpenApi v1. The implementation in v2 will have to wrap the JsonSchema type provided by JsonSchema.NET.

[JsonConverter(typeof(JsonConverter))]
internal sealed class OpenApiJsonSchema(JsonSchema schema)
{
	public JsonSchema Schema { get; } = schema;

	internal sealed class JsonConverter : JsonConverter<OpenApiJsonSchema>
    {
		public override OpenApiJsonSchema? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
		{
			// Use the `Utf8JsonReader` to parse out the opaque type provided by the platform into an
			// OpenApiSchema to be initialized in the platform.
		}
	}
}

The consumption of these shim types will function as follows when used in conjunction with the proposed schema generation APIs in STJ.

var schemaAsJsonObject = JsonSchemaMapper.GetJsonSchema(_jsonSerializerOptions, type, _configuration);
var openApiSchema = JsonSerializer.Deserialize<OpenApiJsonSchema>(schemaAsJsonObject)

I'm prototyping the shape of this shim API in the Microsoft.AspNetCore.OpenApi library as part of our effort to add in built-in OpenAPI document generation support in ASP.NET Core.

Long-term it makes sense for this type to live in the Microsoft.OpenApi package so that it can evolve alongside the OpenAPI specification.

cc: @darrelmiller @eiriktsarpalis

[captainsafia]

The wrapper type has been implemented in Microsoft.AspNetCore.OpenApi as of .NET 9 Preview 4.

After further reflection, I think it's sufficient for the type to stay at this layer of the stack and not move lower to Microsoft.OpenApi.

If we have an explicit requirement that the type would be helpful for consumes of other Microsoft.OpenApi besides ASP.NET Core before a more formal schema type is introduced in System.Text.Json, I'd be happy to turn it into a public API.

For now, I think an internal API resolves the problems sufficiently for our case.