Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add JsonSchemaExporter. #103322

Merged
merged 10 commits into from
Jun 15, 2024
Merged

Conversation

eiriktsarpalis
Copy link
Member

@eiriktsarpalis eiriktsarpalis commented Jun 11, 2024

Fix #102788. This implementation differs somewhat compared to the stj-schema-mapper prototype in a few ways:

  1. Nullable-oblivious reference types are always reported as nullable (this is controlled by a flag in the prototype).
  2. The OnSchemaNodeGenerated callback is invoked for $ref schemas.
  3. $ref schemas are only being generated for recursive types.
  4. { } and {"not": true } node schemas are normalized into true and false respectively.

Copy link

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.

Copy link
Contributor

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

@eiriktsarpalis eiriktsarpalis added this to the 9.0.0 milestone Jun 11, 2024
@dotnet dotnet deleted a comment from dotnet-issue-labeler bot Jun 11, 2024
Copy link
Contributor

@gregsdennis gregsdennis left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The conversions look mostly good. I've left some comments mostly to make other readers aware of the JSON Schema side of things.

@gregsdennis
Copy link
Contributor

gregsdennis commented Jun 12, 2024

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.

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[API Proposal]: Add a JSON schema exporting component for STJ contracts
4 participants