7 Describing data with JSON Schema in OpenAPI

This chapter moves from describing HTTP operations to describing the data those operations exchange, showing how OpenAPI leverages JSON Schema to model, validate, and document API data. It argues against spreadsheets and ad‑hoc documents for data modeling, favoring first‑class, tool‑friendly schemas embedded in the OpenAPI file. The chapter also clarifies practical authoring choices (JSON vs. YAML) and version alignment, noting that OpenAPI 3.1 pairs with a recent JSON Schema edition while most fundamentals remain consistent across versions.

The core practice is to define complete, reusable resource models under components.schemas, independent of any single operation. Schemas typically start with a type, then describe objects via a properties map and required list, covering atomic types (string, integer, number, boolean) and optional formats, as well as nested objects and arrays through items. Marking which fields are mandatory is explicit, and naming conventions for models are flexible. Keeping canonical models centralized improves consistency, accelerates iteration, and provides a clearer view of the API’s subject matter.

With resource models in place, the chapter shows how to wire data into operations. Non‑body elements (path and query parameters, request and response headers) can use inline schemas or reference pieces derived from resource models; array query parameters can have their URL serialization tuned with style and explode. Request and response bodies typically reference reusable schemas through $ref and JSON Pointers, avoiding duplication and drift. The chapter also demonstrates deriving specialized models (for creation/replacement or summaries) and mixing inline structures with references (for example, arrays of referenced items). It advises prioritizing clarity over premature optimization now, with deeper reuse patterns and consolidation left for a later pass.