JSONToTable
Loading JSON Schema to OpenAPI Converter...
Please wait a moment

How to Convert JSON Schema to OpenAPI 3.0 - Step by Step Guide

Wrap JSON Schema definitions into a valid OpenAPI 3.0 components/schemas structure

Step 1

Paste Your JSON Schema

Paste your JSON Schema (Draft-04 through Draft-2020-12). The converter extracts schemas from $defs or definitions and places each one in components/schemas:

•
Paste directly: Paste a JSON Schema from your project, a validation library, or an auto-generated schema
•
Upload a file: Load a .json or .yaml schema file from disk
•
Try the sample: Click "Sample" to load an E-Commerce schema with Products, Orders, and nested $defs

Example: JSON Schema Input with $defs

A JSON Schema with named definitions and $ref references:

{
  "$schema": "https://json-schema.org/draft-07/schema",
  "title": "Product",
  "$defs": {
    "Product": {
      "type": "object",
      "required": ["id", "name"],
      "properties": {
        "id": { "type": "integer" }
        "name": { "$ref": "#/$defs/Name" }
      }
    }
  }
}
Step 2

Auto-Generated OpenAPI 3.0 YAML

The converter wraps your schemas in a complete OpenAPI 3.0 structure and rewrites all $ref paths from JSON Schema format to OpenAPI format:

•
$ref rewriting: #/$defs/Foo and #/definitions/Foo become #/components/schemas/Foo
•
Metadata removed: $schema and $id are stripped — they are not valid in OpenAPI 3.0
•
Complete spec wrapper: Output includes openapi, info, paths, and components so the result is a valid OpenAPI document

Example: Generated OpenAPI 3.0 Output

Schemas placed under components/schemas with rewritten $refs:

openapi: 3.0.3
info:
  title: Product API
  version: 1.0.0
components:
  schemas:
    Product:
      type: object
      required: [id, name]
      properties:
        name:
          $ref: '#/components/schemas/Name'
Step 3

Download, Validate, and Use

The output is a complete OpenAPI 3.0 YAML spec ready to use with any OpenAPI tooling:

•
Validate: Run through our OpenAPI Validator to check the output is a valid OpenAPI 3.0 spec
•
Generate code: Feed the output into our OpenAPI to TypeScript, OpenAPI to Python, or other converters
•
Manual refinement: Add paths, security, and servers to the downloaded YAML to complete your spec

What is JSON Schema to OpenAPI Conversion?

JSON Schema and OpenAPI 3.0 use very similar schema languages — OpenAPI's schema object is a subset of JSON Schema Draft-07. This means most JSON Schema definitions can be used directly inside an OpenAPI spec with only minor adjustments to reference paths and metadata fields.

The key differences this converter handles: JSON Schema stores named schemas under $defs (Draft-2019-09+) or definitions (Draft-07), while OpenAPI stores them under components/schemas. Accordingly, $ref paths like #/$defs/Foo must be rewritten to #/components/schemas/Foo. The $schema and $id meta-schema keywords are also removed as they are not part of the OpenAPI schema object.

After conversion, you'll typically add paths, servers, and security sections to complete the spec. The reverse operation — extracting JSON Schema from OpenAPI — is available via our OpenAPI to JSON Schema converter.

Frequently Asked Questions

What JSON Schema drafts are supported?

Draft-04, Draft-06, Draft-07, Draft-2019-09 and Draft-2020-12. Named schemas are read from definitions (older drafts) or $defs (newer ones), including $defs nested inside another definition. You can paste the schema as JSON or as YAML.

Are all JSON Schema keywords compatible with OpenAPI 3.0?

No, and the converter rewrites the common differences for you: type: ["string", "null"] becomes type: string with nullable: true, const becomes a one-item enum, examples becomes example (the first entry), a numeric exclusiveMinimum or exclusiveMaximum becomes minimum/maximum plus exclusiveMinimum: true, and a $ref with other keywords next to it is wrapped in allOf so those keywords still count. Keywords OpenAPI 3.0 has no slot for, such as if/then/else, patternProperties, propertyNames or dependentRequired, are removed and listed in a note above the output, so you can decide how to express those rules.

What happens to the root schema?

If the root has content of its own (type, properties and so on), it becomes a component named after its title, or "Schema" when there is no title. Every entry in $defs or definitions becomes a component too, and $ref: "#" points at the root component. A root that only holds $defs adds nothing extra. Component names keep only letters, digits, ".", "-" and "_", as OpenAPI requires; a renamed one is mentioned in the note.

Can I reverse this and extract JSON Schema from an OpenAPI spec?

Yes. Use the OpenAPI to JSON Schema converter to pull component schemas out of an OpenAPI 3.0 or Swagger 2.0 spec as standalone JSON Schema files.

Will the output be a complete, valid OpenAPI spec?

It has the required openapi, info and paths fields, and the schemas are written in the form OpenAPI 3.0 expects, so validators such as swagger-parser accept it. The paths object is empty, though: add your endpoints before using it as a real API description. References to other files or URLs are left exactly as you wrote them.

Are long IDs and decimals like 14.50 kept exactly?

Yes for JSON input. Numbers in default, enum, example, minimum, maximum and similar keywords are copied with the same digits you typed, so 8901240544102066246 stays 8901240544102066246 and 14.50 stays 14.50. In YAML input, long integers are kept exactly but a decimal like 14.50 is written as 14.5 (same value). Text such as "00501" stays quoted text.

Is this converter free?

Yes, and there is nothing to sign up for. The conversion runs in your browser, so the schema you paste or upload is not sent to our server.

Related Tools

OpenAPI Validator

Validate OpenAPI 3.0 and Swagger 2.0 specifications online. Check required fields, paths, operations, schemas, and security schemes with instant error reporting.

JSON to OpenAPI

Generate OpenAPI/Swagger specifications from JSON examples. Infer data types and create complete API schemas automatically.

OpenAPI Fixer

Fix broken OpenAPI and Swagger specifications automatically, repair malformed paths, schemas, $ref references, and YAML syntax errors

OpenAPI to Rust

Generate type-safe Rust API client code from OpenAPI/Swagger specifications with serde annotations.

OpenAPI to Go

Generate type-safe Go structs with JSON tags from OpenAPI 3.0 and Swagger 2.0 specifications.

OpenAPI to TypeScript

Convert OpenAPI 3.0 and Swagger 2.0 specifications to TypeScript interfaces and types. Auto-generate type-safe TypeScript from any OpenAPI schema.