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 schema file directly 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?

The converter works with Draft-04, Draft-06, Draft-07, Draft-2019-09, and Draft-2020-12. It handles both definitions (older drafts) and $defs (newer drafts) as sources for named schemas.

Are all JSON Schema keywords compatible with OpenAPI 3.0?

Most core keywords are compatible — type, properties, required, enum, allOf, oneOf, anyOf, items, and format all work directly. JSON Schema-only keywords like const, contentMediaType, and $anchor are not part of OpenAPI and may need manual cleanup after conversion.

What happens to the root schema if it has no $defs?

If the JSON Schema has no $defs or definitions, the root schema itself is placed in components/schemas using the title field as the schema name (or "Schema" if no title is set).

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

Yes. Use our OpenAPI to JSON Schema converter to extract component schemas from an OpenAPI 3.0 or Swagger 2.0 spec as standalone JSON Schema files.

Will the output be a complete, valid OpenAPI spec?

The output includes all required OpenAPI fields (openapi, info, paths) so it passes structural validation. However, the paths object is empty — you will need to add your API endpoints manually. Run the output through our OpenAPI Validator to check it.

Is this converter free?

Yes, completely free with no limits on schema size. No registration required. All conversion runs entirely in your browser — your schema never leaves your device.

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 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.

OpenAPI to Markdown

Convert OpenAPI 3.0 and Swagger 2.0 specifications to readable Markdown API documentation. Generate endpoint tables, parameter docs, and schema references.