Scope and the central split

This guide stays within OpenAPI 3.1.1 and JSON Schema Draft 2020-12. It does not characterize later OpenAPI releases or a particular toolchain.

An OpenAPI document assigns meaning to JSON or YAML material partly through its location in that document. JSON Schema, by contrast, supplies a model for JSON instances and rules for processing schemas. Treat the two as adjacent layers: one describes an HTTP interaction, while the other evaluates payload-oriented data semantics.

This division avoids a common design error: assuming that a schema alone tells consumers which endpoint to call, which HTTP verb to use, which status result is expected, or which security requirement applies.

Responsibility table

Illustrative division of responsibilities for an HTTP API description and its JSON payload schemas
QuestionOpenAPI operation contractJSON Schema payload validation
Where does the interaction occur?Identifies the path and the operation method.Does not select an HTTP route or verb.
How are caller inputs placed?Describes operation parameters and their locations in the interaction.Can describe the structure of a JSON value once that value is chosen for evaluation.
What is sent in the body?Associates a request body and its media-type representation with an operation.Defines instance shape and applicable constraints for the schema-governed payload.
What may come back?Documents response entries, status-oriented outcomes, and response media types.Can model a response representation’s JSON content, but does not define the HTTP response entry.
Who may invoke it?Records security requirements in the operation-description layer.Does not provide the operation’s authentication contract.
How are reusable schemas interpreted?Provides document context for OpenAPI objects and references.Uses mechanisms including references, dialect selection, and vocabulary declarations during schema processing.

The table is an editorial working model, not a normative table from either specification. Its value is diagnostic: keep transport and operation questions on the left, then place JSON-instance questions on the right.

Where a request-body schema belongs

A request body joins the layers rather than replacing either one. In an OpenAPI operation, the request-body area associates a representation with that interaction; a schema beneath the relevant content description expresses the payload’s intended JSON structure.

For example, an operation description can state that a caller sends a particular representation to a particular path using a chosen method, with defined parameters and security. The attached schema can then assess properties, value kinds, constraints, and referenced subschemas for that representation. Neither layer makes the other unnecessary.

{
  "illustrativeOperation": {
    "method": "POST",
    "path": "/orders",
    "requestRepresentation": "application/json",
    "payloadSchemaPurpose": "describe the JSON order value"
  }
}

The JSON object above is illustrative metadata, not an executable OpenAPI document and not evidence that any request succeeds.

A boundary-first troubleshooting method

Start by phrasing the failure as a question. If it concerns routing, method selection, parameter placement, required security, media representation, or an expected HTTP response, inspect the OpenAPI operation description. If it concerns the JSON value’s structure, a constraint, a reference target, a vocabulary, or dialect handling, inspect the schema-processing side.

  1. Locate the relevant path and operation before changing a body schema.
  2. Confirm which request or response representation is being discussed.
  3. Identify the schema resource intended for that representation.
  4. Check references, declared dialect information, and vocabulary expectations before attributing a result to a single field constraint.
  5. Keep a transport-contract defect separate from a payload-evaluation defect in tickets and tests.

This is a recommended workflow based on the standards’ different areas of responsibility; it is not a procedure mandated by either specification.

Alternative starting points

Operation-contract-first design is useful when an API team must settle the callable HTTP surface early. Begin with paths, operations, inputs, responses, and security, then attach schemas to each representation.

Schema-first modeling is useful when a team is building a reusable library of JSON structures. Begin with instance semantics, references, vocabularies, and dialect decisions, then associate the resulting resources with API operations. This approach still needs a separate operation description for HTTP-specific obligations.

A mixed approach can work well: establish the operation boundary first, maintain reusable schemas independently, and make each association explicit. The supplied standards support the underlying separation, but they do not prescribe this team workflow.

Limits of this guide

The supplied material defines specification concepts, not observed behavior from a validator, gateway, documentation renderer, generator, or live service. An implementation’s support for embedded content, references, dialects, and vocabularies must be confirmed from that implementation’s own documentation and tests.

The examples here are explanatory only. They do not demonstrate successful requests, successful validation, interoperability, performance, or enforcement at runtime.