Comparisons••9 min read

OpenAPI vs JSON Schema: Same Syntax, Different Jobs

OpenAPI and JSON Schema look alike but solve different problems. The overlap, the divergence, and how they fit together in a real codebase.

By JSONEditor.net Team

What each one is

JSON Schema is a vocabulary for describing the shape of a JSON document — required fields, types, constraints, formats. It is a standalone IETF specification (currently draft 2020-12) and is consumed by runtime validators in every major language.

OpenAPI (formerly Swagger) is a specification for describing entire HTTP APIs — endpoints, parameters, authentication, request/response shapes. It is maintained by the OpenAPI Initiative under the Linux Foundation and is the format behind Swagger UI, Postman collections, and most code generators.

They look alike because OpenAPI uses JSON Schema for its request and response shapes. A schema fragment that describes a User object is identical between the two — the difference is what surrounds it.

The overlap

Both formats use the same keywords for describing data: type, properties, required, items, enum, format, minLength, minimum, pattern, and so on. A schema like this is valid in both contexts:

{
  "type": "object",
  "required": ["email", "age"],
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0 }
  }
}

OpenAPI 3.1 (released February 2021) aligned its schema subset with JSON Schema draft 2020-12, eliminating the last meaningful incompatibilities. Earlier OpenAPI versions used a slightly different vocabulary, but for new projects the two are interchangeable at the data-shape level.

The differences that matter

Scope. JSON Schema describes a single document. OpenAPI describes a collection of HTTP operations, each with its own request and response schemas plus parameters, headers, security, and metadata.

Endpoint vocabulary. Only OpenAPI has paths, operations, parameters, responses, securitySchemes. Trying to use OpenAPI to validate a standalone JSON file is overkill; trying to use JSON Schema to describe an HTTP API is impossible without inventing the wrapping yourself.

References. JSON Schema uses $ref with $id for cross-document linking. OpenAPI follows the same syntax but keeps reusable components under #/components/schemas rather than scattered files.

Validation strictness. JSON Schema validators are usually configured to fail on any deviation. OpenAPI tooling tends to be more permissive — Swagger UI will render a partially invalid spec, code generators will skip unknown keywords. That difference is the source of "but it works in Swagger UI" debugging sessions.

When to use which

Use JSON Schema alone when:

  • You are validating a config file (package.json, tsconfig.json) or any standalone JSON document.
  • You are validating a message format (queue payloads, event-bus messages) outside an HTTP context.
  • You want runtime validation in a server without the HTTP surface area.
  • You are generating types from a data shape definition.

Use OpenAPI when:

  • You are describing an HTTP API for client generation (TypeScript SDK, Python client, Postman collection).
  • You want interactive documentation (Swagger UI, Redoc).
  • You want contract testing — Pact, Dredd, Schemathesis all read OpenAPI.
  • Your API has more than five endpoints and you need a single source of truth for the surface.

Using them together

The pattern that works in real codebases: write OpenAPI for the HTTP surface, extract the JSON Schema fragments for runtime validation. Most stacks have a tool that does this automatically:

// FastAPI (Python) — both at once, from one Pydantic model
class User(BaseModel):
  email: EmailStr
  age: int = Field(ge=0)

# OpenAPI spec auto-generated at /openapi.json
# JSON Schema validation enforced on every request body

// Express + zod-to-openapi
const userSchema = z.object({
  email: z.string().email(),
  age: z.number().int().min(0),
});
// z.parse → runtime check
// openApiRegistry.register → spec generation

The single-source-of-truth approach (define once, generate both) eliminates the divergence between the documented contract and the enforced one. Without it, the OpenAPI spec drifts — fields are added in code without spec updates, examples in the docs no longer parse, validation rules become aspirational.

The tooling landscape

The two ecosystems are roughly comparable in maturity. For JSON Schema, Ajv is the runtime standard, with bindings in every major language. The browser validator on this site uses it for instant feedback during schema development.

For OpenAPI, the big four are Swagger UI (interactive docs), Redoc (alternative renderer), openapi-generator (clients in 50+ languages), and Spectral (linting). If you maintain a public API, you almost certainly want all four wired into CI.

Bottom line: the two specs are friends, not competitors. JSON Schema is the data-shape primitive that OpenAPI builds on. Pick OpenAPI when you have an HTTP API; pick JSON Schema when you do not. Use them together when you have both an API and per-message validation needs — which is most non-trivial systems.

JSONCSVConvertersData