json-schema-for-openapi

json-schema-for-openapi

Converts a standard JSON Schema to a compatible OpenAPI v3.0.X Schema Object.

As of version 0.3.0, it is now advised to run a schema through a de-referencer like: https://apitools.dev/json-schema-ref-parser/ to properly deal with $ref. I have removed my own poor implementation of de-referencing JSON schemas since there are libraries that can do it better than I can.

It should be noted, that de-referencing libraries have their own issues and might not be able to properly parse your JSON/output a schema you might expect. Due to the way OpenAPI v3.0.X Schema Object's are handled, should the referencing not be 100% correct you might face issues using this library and its output to be used with OpenAPI 3.0.X.

Conversions

This attempts to massage the standard JSON Schema to a compatible OpenAPI v3.0.X Schema Object. There are many properties that are not supported by OpenAPI v3.0.X Schema Object, though have now been supported by OpenAPI v3.1.X. This library should only be used if working with OpenAPI v3.0.X.

Items as an Array to Object

This will convert a schema of:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "array",
      "items": [
        {
          "type": "string"
        }
      ]
    }
  }
}

To:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

At the moment, this library cannot handle more than one item in the array, and so will default to using the first item only.

Types in an array to OneOf

This will convert a schema of:

{
  "type": "object",
  "properties": {
    "example": {
      "type": ["string", "number"]
    }
  }
}

To:

{
  "type": "object",
  "properties": {
    "example": {
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}

Where an array contains null, it will now set nullable against all types:

{
  "type": "object",
  "properties": {
    "example": {
      "type": ["string", "number", "null"]
    }
  }
}

To:

{
  "type": "object",
  "properties": {
    "example": {
      "oneOf": [
        {
          "type": "string",
          "nullable": true
        },
        {
          "type": "number",
          "nullable": true
        }
      ]
    }
  }
}

Const to enum

This will convert a schema of:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "string",
      "const": "Surburbia"
    }
  }
}

To:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "string",
      "enum": ["Surburbia"]
    }
  }
}

null types

OpenAPI 3.0.X does not allow for null as a type, so will convert a schema of:

{
  "type": "object",
  "properties": {
    "example": {
      "type": "null"
    }
  }
}

To:

{
  "type": "object",
  "properties": {
    "example": {
      "nullable": true
    }
  }
}

Default to their type

This will convert the "default": value to the relevant type. A String to a String, a Number/Integer to a number/Integer, a Boolean to a Boolean and try to manipulate an Object or an Array to either an Object or an Array

Dependencies, DependentRequired, DependentSchemas

This will try to convert "dependencies":, "dependentRequired": and "dependentSchemas": to a valid "allOf" in the case of a "dependentSchemas" or an "anyOf": schema in the case of a "dependentRequired".

If/Then/Else

It will try to convert an If/Then/Else schema statement to a valid "OneOf" schema.

Installation and Usage:

Install via npm: npm install json-schema-for-openapi.

And use as a Factory like:

const ConvertorFactory = require("json-schema-for-openapi");
const jsonSchema = {
  $schema: "http://json-schema.org/draft-04/schema#",
  title: "JSON API Schema",
  description:
    "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
  type: "object",
  properties: {
    errors: {
      type: "object",
    },
  },
};
const convertedSchema = ConvertorFactory.convert(jsonSchema, "main");

which will output:

{
  "schemas": {
    "main": {
      "title": "JSON API Schema",
      "description": "This is a schema for responses in the JSON API format. For more, see http://jsonapi.org",
      "type": "object",
      "properties": {
        "errors": {
          "type": "object"
        }
      }
    }
  }
}