Skip to content
Numio

JSON Schema to OpenAPI Specs Converter — Numio

Converts a JSON Schema (draft-04 and later) into an OpenAPI 3.0 Schema Object. Type arrays containing "null" become "nullable: true", const becomes a one-item enum, and examples becomes a single example.

You validate payloads with a draft-07 schema and need the same model under components/schemas in an OpenAPI 3.0 document.

JSON Schema

Open API Schema

When to use it

  • You validate payloads with a draft-07 schema and need the same model under components/schemas in an OpenAPI 3.0 document.
  • Your OpenAPI 3.0 tooling rejects "type": ["string", "null"] and you need nullable fields rewritten.

How to use

  1. Paste a JSON Schema into the JSON Schema panel; it must be valid JSON because the page parses it before sending.
  2. The schema is posted to /api/json-schema-to-openapi-schema and converted on the server; the panel shows a notice saying so.
  3. Copy the result from the Open API Schema panel and place it under components/schemas in your OpenAPI file.

JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "kind": { "const": "invoice" },
    "total": { "type": ["number", "null"], "exclusiveMinimum": 0 },
    "notes": { "type": "string", "examples": ["Net 30"] }
  },
  "required": ["kind"]
}

OpenAPI 3.0 Schema Object

{
  "type": "object",
  "properties": {
    "kind": {
      "enum": [
        "invoice"
      ]
    },
    "total": {
      "type": "number",
      "exclusiveMinimum": true,
      "nullable": true,
      "minimum": 0
    },
    "notes": {
      "type": "string",
      "example": "Net 30"
    }
  },
  "required": [
    "kind"
  ]
}

Details and limitations

The page sends your input to a server route (/api/json-schema-to-openapi-schema) for conversion; it is not processed only in the browser. Next.js API routes accept request bodies up to 1 MB by default.

The $schema keyword is removed. Numeric exclusiveMinimum/exclusiveMaximum are rewritten to the OpenAPI 3.0 form: minimum/maximum plus a boolean flag.

$ref values are left as they are and definitions are not moved to components/schemas, so you must fix reference paths yourself.

The target is OpenAPI 3.0. OpenAPI 3.1 already uses JSON Schema directly and usually needs no conversion.

FAQ

How are nullable types converted?

A type array such as ["number", "null"] becomes "type": "number" with "nullable": true, as in the example.

Does it resolve $ref references?

No. The page does not dereference; "$ref": "#/definitions/Tag" and the definitions block are copied through unchanged.

What happens to const and examples?

const becomes an enum with one value, and the examples array is replaced by a single example taken from its first item.

Specifications and references