Background and motivation

The recent popularity of function calling capabilities in LLMs as well as the upcoming OpenAPI work in ASP.NET Core has highlighted the importance of a System.Text.Json component that is capable of exporting its own serialization contracts (JsonTypeInfo) to JSON schema documents. Such a component should ideally satisfy the following criteria:

1. The resultant JSON schema should honor configuration as specified in JsonSerializerOptions and POCO attribute annotations (e.g. JsonNamingPolicy, JsonNumberHandling, JsonPropertyName, JsonIgnore, etc.)
2. The resultant JSON schema should be consistent with STJ serialization semantics. That is to say that all JSON produced by the serializer should be valid under the schema, and all JSON that is valid under the schema should be accepted by the deserializer.
3. The component should support .NET standard 2.0 and .NET framework.
4. The component should support source generated contracts and be compatible with Native AOT.

I wrote a prototype that attempts to address the above design goals, and this was largely achieved by tapping into the metadata exposed by the STJ contract model. That being said, the existing contract APIs do not expose all metadata that is necessary to construct a schema, so in many cases the implementation had to resort to private reflection or outright replication of STJ internals. At the same time, the core mapping logic itself requires acute understanding of STJ esoterica, so it cannot be expected that such a component could be sustainably maintained by third-party authors.

I'm creating this issue to track .NET 9 work related to JSON schema extraction. The scope is related to and overlaps with #29887 but doesn't necessarily coincide with it. At a high level, it is tracking the following goals (in order of importance):

1. Expose new APIs in the contract model that make it possible to extract the schema without use of private reflection or duplication of internal STJ logic.
2. Add a built-in component mapping JsonTypeInfo contracts to JSON schema documents. Most users should able to use that directly, but would also serve as a reference implementation for those that want to map to bespoke formats (e.g. OpenAPI YAML).
3. Add a JsonSchema exchange type. This is a stretch goal for .NET 9 since it would likely necessitate implementing support for the full JSON schema specification (whereas a mapper need only target a subset of the spec).

Work Items

1. Contract API extensions & enhancements
   • JsonObject should support property order manipulation #102932
   • Expose enum type contract metadata (int vs string serialization, custom naming policies, etc.)
   • Expose Nullable<T> contract metadata (element type, custom element converters, etc.)
   • Add a STJ feature flag treating non-optional constructor parameters as required #100075
   • Expose ElementType and KeyType on JsonTypeInfo metadata. #77306
   • [System.Text.Json] Expose additional metadata in contract APIs. #102078
   • Add a STJ feature flag recognizing nullable reference type annotations on properties #100144
   • The System.Text.Json source generator doesn't populate JsonPropertyInfo.AttributeProvider metadata. #100095
2. Built-in schema mapper
   • [API Proposal]: Add a JSON schema exporting component for STJ contracts #102788
3. JSON schema exchange type. (Cut for .NET 9)