Note regarding the new-api-needs-documentation label:

This serves as a reminder for when your PR is modifying a ref *.cs file and adding/modifying public APIs, please make sure the API implementation in the src *.cs file is documented with triple slash comments, so the PR reviewers can sign off that change.

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

Summarizing my inline comments here that were intended to give other reviewers some JSON Schema context.

Usage of $ref with JSON Pointers

JSON Schema (the org, not the spec) recommends a best practice where a $ref with a JSON Pointer SHOULD only point to an immediate child of the $defs keyword. It SHOULD NOT drill down into other keywords. The exception to pointing to the $defs keyword is when it just points to the schema root.

While many JSON Schema tools do support pointers into other areas of the schema, such behavior is not a requirement and cannot be relied upon.

The exporter in its current state uses $ref to create recursive schemas as is appropriate for recursive data structures. However when that recursive structure appears under a property, the exporter generates a $ref that points into the properties keyword:

{
  "type": "object",
  "properties": {
    "linkedList": {
      "type": "object",
      "properties": {
        "value": { "type": "number" },
        "next": { "$ref": "#/properties/linkedList" }
      }
    }
  }
}

This should be refactored to extract the linked list (really a node) into a $defs keyword which can be the reference target for the linkedList property:

{
  "type": "object",
  "properties": {
    "linkedList": { "$ref": "#/$defs/linkedListNode" }
  },
  "$defs": {
    "linkedListNode": {
      "type": "object",
      "properties": {
        "value": { "type": "number" },
        "next": { "$ref": "#/$defs/linkedListNode" }
      }
    }
  }
}

This helps to identify the subschema as something that is intended to be reused.

Other approaches to this are demonstrated in the tests, but these are opt-in behaviors.

• Creating an $anchor keyword that the $ref can use.
• Creating an $id keyword that the $ref can use.

My primary concern about moving forward with the current implementation is that .Net has a rather wide reach, and intentionally releasing something that goes against recommended best practice will only encourage others to do the same.

format

The format keyword is only an annotation (by default) and provides no validation behavior. Implementations MAY support validation for it (many do), but it's not a requirement. Mine does, and the local unit tests have configured it to do so.

In the JSON Schema Test Suite, all format validation tests are optional.

Date & time formats

JSON Schema's date/time formats use RFC3339, but .Net uses ISO8601. (Ref: #85545). Here's a handy comparison site: Comparison.

enum

Specifying type is redundant when enum is also present. enum declares all of the acceptable values (which may be of any JSON type). But if all of those values are strings, then type: string is implied.