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.

7.1 An overview of describing data

7.1.1 Introducing JSON Schema

7.1.2 Contrasting OpenAPI and JSON Schema with our API spreadsheet

7.1.3 Describing data while designing it

7.2 Authoring a JSON Schema data model in OpenAPI

7.3 Adding complete resource data models to the OpenAPI document

7.3.1 Choosing a location for the resource model in the OpenAPI document

7.3.2 Initiating the resource model description

7.4 Describing complete resource data models with JSON Schema

7.4.1 Describing an object

7.4.2 Adding properties to an object

7.4.3 Describing an atomic property

7.4.4 Describing an object property

7.4.5 Describing an array property

7.4.6 Stating which properties are required

7.5 Describing operation input and output data

7.6 Describing operation non-body data

7.6.1 Describing non-body request parameters with inline schemas

7.6.2 Tweaking non-atomic parameter serialization

Summary