[JsonSchemaExporter]: Respecting data annotations + schema version

[marekott]

Background and motivation

When trying to migrate from Newtonsoft.Json.Schema to pure JsonSchemaExporter (without any third party libraries) I have noticed that at least two features are missing.

1. Respecting data annotations (for example including in schema min and max of given type)
2. Possibility to select schema draft version

Would you guys consider adding them so the transition would be possible without taking dependency on external libraries?

Newtonsoft.Json.Schema:

{
  "$schema" : "http://json-schema.org/draft-07/schema#",
  "definitions" : {
    "Nested<UInt16>" : {
      "type" : "object",
      "properties" : {
        "required" : {
          "type" : "integer",
          "minimum" : 0.0,
          "maximum" : 65535.0
        },
        "nullable" : {
          "type" : [ "integer", "null" ],
          "minimum" : 0.0,
          "maximum" : 65535.0
        }
      },
      "required" : [ "required" ]
    }
  },
  "type" : "object",
  "properties" : {
    "required" : {
      "type" : "integer",
      "minimum" : 0.0,
      "maximum" : 65535.0
    },
    "nullable" : {
      "type" : [ "integer", "null" ],
      "minimum" : 0.0,
      "maximum" : 65535.0
    },
    "nested" : {
      "$ref" : "#/definitions/Nested<UInt16>"
    }
  },
  "required" : [ "required", "nested" ]
}

STJ:

{
  "type" : [ "object", "null" ],
  "properties" : {
    "required" : {
      "type" : "integer"
    },
    "nullable" : {
      "type" : [ "integer", "null" ]
    },
    "nested" : {
      "type" : "object",
      "properties" : {
        "required" : {
          "type" : "integer"
        },
        "nullable" : {
          "type" : [ "integer", "null" ]
        }
      },
      "required" : [ "required", "nullable" ]
    }
  },
  "required" : [ "required", "nullable", "nested" ]
}

API Proposal

JsonSerializerOptions options = new(JsonSerializerOptions.Default)
{
    RespectDataAnnotations= true,
    Version = "draft-07"
};

API Usage

JsonSerializerOptions options = new(JsonSerializerOptions.Default)
{
    PropertyNamingPolicy = JsonNamingPolicy.KebabCaseUpper,
    NumberHandling = JsonNumberHandling.WriteAsString,
    UnmappedMemberHandling = JsonUnmappedMemberHandling.Disallow,
    RespectDataAnnotations= true,
    Version = "draft-07"
};

JsonNode schema = options.GetJsonSchemaAsNode(typeof(MyPoco));
Console.WriteLine(schema.ToString());

Alternative Designs

No response

Risks

No response

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-text-json, @gregsdennis
See info in area-owners.md if you want to be subscribed.

[eiriktsarpalis]

For data annotations support specifically, it is something we have been intentionally avoiding so far because we didn't want System.Text.Json to take a dependency on System.ComponentModel.DataAnnotations. Components depending on JsonSchemaExporter such as ASP.NET OpenAPI and Microsoft.Extensions.AI typically incorporate support for data annotations by implementing custom transformer delegates.

It does make me wonder if we could make the JsonSchemaExporter read those attributes without depending on them using reflection. We already do this in STJ for System.Collections.Immutable and FSharp.Core. @stephentoub @captainsafia thoughts?

[stephentoub]

read those attributes without depending on them using reflection

How, and specifically how for the ones where it's not just the presence of the attribute that matters but specific properties on it?

[eiriktsarpalis]

The contract model already exposes ICustomAttributeProvider instances that report attributes for types and properties in a trim-safe manner. Getting to actual properties within attributes is an open question from a trimmability perspective, but maybe there are tricks we can use to get it to work.

[eiriktsarpalis]

For example, we can use DynamicDependencyAttribute to instruct the linker to not trim specific members identified by string.

[stephentoub]

If we can make it work reliably and safely, I'm for it.