A schema is a formal description of exchanged data: its shape, properties, required fields, types, constraints, and human-readable annotations. In API design, schemas make request and response data understandable, reusable, documentable, and testable. section 7.1.1 section 7.8
JSON Schema operates independently of OpenAPI, while OpenAPI embeds it in request bodies, responses, and headers. A schema can validate JSON or YAML, support documentation and mocking, and contribute to testing or interface generation. section 7.1.1 section 7.8
Modeling a product API
A product API can define its complete Product model once under components.schemas, then reference it from multiple operations. A creation or replacement model can likewise serve both POST /products and PUT /products/{productReference}. This avoids copy-and-paste differences and keeps related operations consistent. section 7.3.1 section 7.7.3
Choose the schema location and structure according to the data’s role:
- Put operation input and output schemas inside the relevant requestBody or response content schema property. section 6.8.1 section 7.8
- Define complete, reusable resource models under components.schemas when several operations share them. section 7.3.1
- Use $ref with a JSON Pointer such as #/components/schemas/Product to reference a reusable model instead of duplicating it. section 7.7.3 section 7.8
- Use an inline schema for small, operation-specific data, such as a string-valued Location response header. section 7.6.3 section 7.8
Listing 6.10 Response bodies
...
paths:
/products:
summary: Catalog
...
post:
summary: Add a product to the catalog
...
responses:
"201":
description: Product added to the catalog
content: #1
application/json: #2
schema:
description: Product info. #3
"400":
description: Wrong product information
content: #4
application/json: #5
schema:
description: Error info.
"500":
description: Unexpected server error
content: #6
application/json: #7
schema:
description: Error info.
Inspect a response definition showing JSON media types, response descriptions, and separate schema descriptions for successful and error responses. section 6.8.1
Listing 7.15 References to reusable schemas
...
paths:
/products:
...
post:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas
<linearrow/>/ProductCreationOrReplacement" #1
...
/products/{productReference}:
...
put:
requestBody:
content:
application/json:
schema:
$ref: "#/components/schemas
<linearrow/>/ProductCreationOrReplacement" #1
...
components:
schemas:
...
ProductCreationOrReplacement: ... #1
Inspect how POST and PUT request bodies reference the same reusable ProductCreationOrReplacement schema. section 7.7.3
