chapter seven
7 Describing data with JSON Schema in OpenAPI
This chapter covers
- When and how to leverage data description capabilities of OpenAPI during API design
- Describing data with JSON Schema in the context of OpenAPI
- Describing reusable resource data models with JSON Schema in an OpenAPI document
- Describing operations input and output data with JSON Schema in an OpenAPI document
Once we have described the HTTP operations with OpenAPI, we can move on to the next step and leverage JSON Schema to describe the fine-grained data. As discussed in chapter 6, using such standards simplifies the API design process, reduces errors, and benefits the whole API lifecycle.
This chapter introduces the JSON Schema format and overviews how to describe data while designing it. It then briefly discusses JSON Schema authoring in the context of OpenAPI authoring. The rest of the chapter describes the "Online Shopping" data modeled in chapter 5 with JSON Schema and OpenAPI, demonstrating how to describe resource models and use them to describe operations input and output data based on their locations.