Search code examples
.netjson.netopenapijsonschemaanthropic

Why the `Items` property within `Newtonsoft.Json.Schema` is represented as a `IList<JSchema>`?

According to the documentation of JSON Schema, the value of "items" MUST be a valid JSON Schema itself for the subschema, while within the Newtonsoft.Json.Schema package, Items are represented as a list of JSchema.

I'm using the Anthropic library from tryAGI, where they represent it as an OpenApiSchema, which aligns to the definition of a JSON Schema.

public OpenApiSchema? Items { get; set; }

I'm using AutoMapper to map my JSchema to an OpenApiSchema, but it's failing because the property in Newtonsoft.Json.Schema being a List.

JSchemaGenerator generator = new JSchemaGenerator();
JSchema schema = generator.Generate(typeof(Person));
var openApiSchema = _mapper.Map<OpenApiSchema>(schema);

Why the Items property is reflected as a List within Newtonsoft.Json.Schema, while it should be a JSchema itself, isn't it?

Solution

  • Couple things here...

    • your reference to the JSON Schema documentation is for Draft 2020-12, where items can only be a valid JSON Schema, {} or true. This was updated in the latest draft and a new keyword prefixItems was introduced for a list of schemas
    • items can be either an object or an array in JSON Schema Draft-04 - Draft-2019-09. Newtonsoft should support both, (I'm not sure if they do, although I would be very surprised if they didn't)
    • items as a list is not valid in OpenAPI 3.0.x

    an OpenApiSchema, which aligns to the definition of a JSON Schema.

    This is not entirely accurate. An OAS Schema is a subset and a superset of JSON Schema draft-04 specification. An OAS Schema does not support all keywords in a JSON Schema schema. e.g. items

    Here's the full text from the OpenAPI Specification

    The following properties are taken from the JSON Schema definition but their definitions were adjusted to the OpenAPI Specification.

    • type - Value MUST be a string. Multiple types via an array are not supported.
    • allOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
    • oneOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
    • anyOf - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
    • not - Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema.
    • items - Value MUST be an object and not an array. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. items MUST be present if the type is array.
    • properties - Property definitions MUST be a Schema Object and not a standard JSON Schema (inline or referenced).
    • additionalProperties - Value can be boolean or object. Inline or referenced schema MUST be of a Schema Object and not a standard JSON Schema. Consistent with JSON Schema, additionalProperties defaults to true.
    • description - [CommonMark] syntax MAY be used for rich text representation.
    • format - See Data Type Formats for further details. While relying on JSON Schema’s defined formats, the OAS offers a few additional predefined formats.
    • default - The default value represents what would be assumed by the consumer of the input as the value of the schema if one is not provided. Unlike JSON Schema, the value MUST conform to the defined type for the Schema Object defined at the same level. For example, if type is string, then default can be "foo" but cannot be 1.