7 Describing data with JSON Schema in OpenAPI
This chapter covers
- JSON Schema within OpenAPI
- Describing resource data
- Describing request parameters data
- Describing request and response bodies data
- Describing response headers data
Once we have described the HTTP operations with OpenAPI, we can move on to the next step and describe their data. Describing data models in a spreadsheet, word processor document, or wiki page is technically possible. However, though we used a spreadsheet for learning purposes, we must not use such formats for the same reasons why they were not suitable for describing HTTP operations: they are not made for his task, authoring and maintaining such documents can be complex and error-prone, and their use is limited to reading them. Instead, we continue using OpenAPI, which leverages another standard called JSON Schema to describe data.
This chapter introduces the JSON Schema format and provides an overview of how to describe data while designing it. It briefly discusses JSON Schema authoring in the context of OpenAPI. Then, it explains how to describe resource data models with JSON Schema in an OpenAPI document and leverage them as inputs and outputs for operations.