7 Describing data with JSON Schema in OpenAPI
This chapter covers
- Using JSON in OpenAPI
- Describing resource data
- Describing request parameter data
- Describing request and response body data
- Describing response header 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, although we used a spreadsheet for learning purposes, we must not use such formats for the same reasons they are not suitable for describing HTTP operations: they are not made for this 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 uses 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. We briefly discuss JSON Schema authoring in the context of OpenAPI. Then we explain how to describe resource data models with JSON Schema in an OpenAPI document and use them as inputs and outputs for operations.