Schema validation for null values with OpenAPI (swagger) JSON schema definitions

Question

I am looking for a solution to resolve the incompatibility for handling null values for data types between Swagger (OpenAPI) data types and JSON Schema.

Our swagger file includes all our schema definitions, and I would like to use JSON.Net Schema for the schema validation step in our API tests.

A valid swagger property definition:

  "description": {
    "type": "string",
    "nullable": true
  }

will fail JSON schema validation for null values (Invalid type. Expected String but got Null).

If I replace the nullable property definition with:

  "description": {
    "type": ["string", "null"]
  } 

validation will be successful for null values, but this breaks the swagger syntax.

Structural error at components.schemas.CalendarFunctionsDto.properties.description_EN.type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string

I couldn't find an OpenAPI schema to JSON schema converter for .NET. I'm trying to figure out if there is an easy solution available using JSON.Net Schema to solve this problem. Some of our types are more complex than the example above. I am looking for a solution that works for all "nullable" types.

I would ideally like to keep valid swagger (OpenAPI 3.0) JSON syntax for the input, programmatically perform some spells in C# for all nullable properties (convert the schema, or adjust the validation, or any other creative solution), and then validate the schema using JSON.Net Schema.

Answer 1

Openapi 3.0.0/3.0.1/3.0.2/3.0.3 does not support the null type, it only supports nullable. JSON Schema does not support nullable, it supports the null type. Can you update your spec to Openapi v3.1.0? That version supports the null type. Then you can use one of these options:

Option 1 (unlikely to work in openapi tooling because arrays of types are such a new addition)

  "description": {
    "type": ["string", "null"]
  } 

Option 2 (more likely to work with openpi tooling because type is not an array)

  "description": {
    "oneOf" [
        {"type": "string"},
        {"type": "null"},
    ]
  }