Defining Schemas and Responses

A successful JSON example shows what one response looks like, but it cannot describe every possible outcome. For a bookstore lookup, a client still needs to know which fields always exist, whether an empty author list is valid, and what arrives when the book is missing. It may also need the response's cache validator. The example body alone cannot answer all of those questions.

OpenAPI uses schemas to describe data and Response Objects to describe HTTP outcomes.

This chapter explains how to connect them, model objects and collections, distinguish alternative shapes, and document success and failure without leaving important behavior implicit. The examples use OpenAPI 3.1.2 and a fictional bookstore over HTTPS.