Apply schema transformers on properties and other subschemas

[captainsafia]

Closes #56584.

Schema transformers are currently only called on schemas that are generated at the top-level for respones, parameters, and request bodies. This PR allows schema transformers to be applied recursively into sub-schemas that might appear in these arguments (for example, the schema for an int property that is part of a Todo type). We currently apply transformations to subschema types where we understand how to resolve TypeInfo for them:

• schema.items: for schemas that represent lists of elements
• schema.anyOf: for schemas that represent polymorphic schemas with subtypes
• schema.properties: for schemas associated with properties in a type

Changes in this PR include:

• Remove the OpenApiSchemaTransformerContext.Type property and adding OpenApiSchemaTransformerContext.JsonTypeInfo and OpenApiSchemaTransformerContext.JsonPropertyInfo
• Changes to OpenApiSchemaService to support applying schemas recursively into the subschemas mentioned above
• Additional tests in SchemaTransformerTests to cover relevant scenarios

Note: One of the new tests introduced here (SchemaTransformer_CanModifyListOfPolymorphicTypes) is currently skipped because of a bug I discovered in ApplyPolymorphismOptions where we don't handle things correctly if a polymorphic type is a child of another type (like List<Shape> or a type with a Shape property) because of the context.Path.Length == 0 check we currently use to check for base types. This should be resolved once we have can consume dotnet/runtime#104046 in an upcoming runtime update.

Another note: I'm hoping to bring these changes in to #56599 for more complete perf coverage for these transformer types.

[mikekistler]

I left a few comments/questions that I hope are helpful.

[captainsafia]

I left a few comments/questions that I hope are helpful.

Posting a response to all the comments here since they all relate to the same concept: the constraint associated with this implementation that we only apply transformations to subschemas that we can resolve a JsonTypeInfo for. The subschemas that we don't recurse into are:

• schema.not
• schema.allOf
• schema.oneOf
• schema.additionalProperties

If a user sets one of these subschemas explicitly in their own transformer, we have no way of constructing a complete context object for it because we don't know the type associated with the schema.

options.UseSchemaTransformer((schema, context, cancellationToken) =>
{
	// What is the JsonTypInfo assocaited with this schema?
	schema.Not = new OpenApiSchema { Type = "string" };
});

There's two approaches to solving this:

We could relax the constraints on the OpenApiSchemaTransformerContext so that the JsonTypeInfo is optional and recurse into the subschemas above. At the point, there's no way for you to know what the context of the schema you're modifying is. Is it a not schema, is it an allOf? There's no way to tell without adding additional state to the context object.

Alternatively, we could set the OpenApiSchemaTransformerContext.JsonTypeInfo property to the parent type associated with the schema (for example, a not inside a Todo schema would have JsonTypeInfo = Todo. This has the opposite problem though: you'd recurse into a schema with the wrong type and potentially make unexpected modifications to the target schema.

So, stuck between a rock and a hard place, I opted not to recurse into these as part of the default implementation. If a user explicitly needs it though, it should be possible to construct their own schema transformer implementation that supports the recursion into these properties and they can initialize the OpenApiSchemaTransformerContext with whatever state makes sense for their scenario. I'll add a test to model how I think this approach would look.

Let me know if you have any other questions or if there is some other way to solve the ambigous context problem.

[captainsafia]

Bump for reviews! Hoping to get this in before Friday...

[martincostello]

FWIW I had a look at it last week and didn't spot anything.

[BrennanConroy]

My only worry is the implicit relationship between schema properties and jsonTypeInfo. Any sensible bounds checking we can add?

[BrennanConroy]

schema.AnyOf[anyOfIndex]

I don't see any bounds checking here. If it's done earlier, it's far from this callsite and doesn't feel safe.

[captainsafia]

Yeah, this takes an assumption on the implementation details of the schema generator which generates the anyOf child schemas based on the ordering in JsonTypeInfo.DerivedTypes. I added a check here but things will get spooky for people if they are inserting subschemas into anyOf that don't match what is understood by STJ from the derived type attributes.

[BrennanConroy]

Same kind of deal, it seems like there is an implicit very close relationship between schema and jsonTypeInfo?

[captainsafia]

Yep, I introduced a check here to only apply transformers on properties with matching names. This does mean that there is a gap for scenarios where a user applies a schema transformer that changes the casing/format of property keys in a way to is inconsistent with how System.Text.Json is configured. In that case, they'd have to fallback to applying the recursion manually themselves in a top-level schema transformer since this would no-op.