liveBook · Manning

Components.schemas

As explained in The Design of Web APIs, Second Edition

components.schemas is the OpenAPI document section that stores reusable named data schemas independently of individual operations.

components.schemas stores reusable, named JSON Schemas independently of individual operations. This separates complete resource models from their uses, improving consistency, maintainability, and the API’s subject-matter view. section 7.3.1 section 7.8

A reusable Product model

Define Product once under components.schemas, then reference it from request and response schemas with $ref: #/components/schemas/Product. This avoids copied definitions and unwanted variations. section 7.3.2 section 7.8

Listing 7.1 Reusable schema
openapi: 3.1.0

info: ...

paths: ...

components:   #1
  schemas:           #2
    Product: {}      #3

The minimal structure places schemas inside components; Product is a named, initially empty Schema object. section 7.3.2

How The Design of Web APIs, Second Edition covers it

How deep it goes
Defines placement, naming, references, derivations, and consistency trade-offs, while deferring detailed JSON Schema construction.
Examples
Uses a Product schema and a minimal OpenAPI 3.1.0 YAML structure.
What it assumes
Assumes familiarity with OpenAPI operations and JSON Schema data descriptions.
What you can do after
Build reusable resource schemas and apply them across request and response bodies with JSON Pointers.
How it connects
Connects OpenAPI operations, JSON Schema, resource models, $ref, allOf, readOnly, and writeOnly.
Cover of The Design of Web APIs, Second Edition
liveBookmanning.com
Read The Design of Web APIs, Second Edition on liveBook Get the book at manning.com

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.