JSON Schema to OpenAPI
Convert a JSON Schema into the dialect OpenAPI expects. For 3.0 that means rewriting type: ["string", "null"] as nullable: true, const as a single-value enum, examples as example, and dropping keywords 3.0 has no equivalent for. Every adjustment is reported.
How to convert JSON Schema to an OpenAPI schema
- Paste your JSON Schema.
- Pick the target. 3.1 is a proper JSON Schema 2020-12 superset, so very little changes; 3.0 uses an older, divergent subset and needs real rewriting.
- Tick Wrap in a components/schemas document to get a fragment you can drop straight into a spec file, with
$defspromoted alongside it. - Read the adjustment list in the status bar — anything dropped is named there.
- Copy or download the result.
OpenAPI 3.0 versus 3.1
This is the single most confusing thing about schemas in OpenAPI, so it is worth stating plainly:
- OpenAPI 3.0 uses a modified subset of JSON Schema draft-04/05. It has its own
nullableflag, noconst, only a singularexample, and no support forif/then,unevaluatedProperties, orprefixItems. - OpenAPI 3.1 aligned with JSON Schema 2020-12 completely.
nullableis gone — you writetype: ["string", "null"]— and every 2020-12 keyword is legal.
If you can target 3.1, do; the conversion is nearly a no-op and nothing is lost. Target 3.0 only when your tooling requires it, and expect to lose expressiveness.
Every 3.0 rewrite
type: ["X", "null"]→type: Xplusnullable: true.- A union of two or more non-null types →
oneOf, since 3.0'stypetakes a single string. const: x→enum: [x].examples: [a, b]→example: a. The remaining examples are lost; 3.0 has no plural form on a schema.- Numeric
exclusiveMinimum/exclusiveMaximum→ the bound plus a boolean flag, the draft-04 spelling. prefixItems→ collapsed toitems: {oneOf: […]}, which is looser: it no longer pins types to positions.$defs/definitions→ promoted tocomponents/schemas, with$refs repointed.- Dropped entirely —
if,then,else,dependentSchemas,dependentRequired,unevaluatedProperties,unevaluatedItems,contentEncoding,contentMediaType,$comment. Anything that depended on these for validation stops being enforced.
Privacy
Nothing is uploaded. The conversion runs in this tab using your own browser's JavaScript engine — no server sees your data, and the page keeps working with the network disconnected.
FAQ
Does it produce a complete OpenAPI document?
No — it produces the schema object, optionally wrapped in components/schemas. Paths, operations and responses describe your API's behaviour, which a schema alone cannot tell you.
Can it go the other way?
Yes — OpenAPI → JSON Schema extracts each component as a standalone schema, converting nullable back into a type union.
Why did dropping if/then not warn me more loudly?
It is listed in the status bar with its path. It is worth taking seriously: a conditional constraint silently disappearing means documents that should be rejected will pass. If your schema leans on conditionals, target 3.1.