JSON Schema is an independent format for validating and annotating JSON or YAML data. In OpenAPI, it gives data models machine-readable meaning for API design, documentation, mocking, testing, and code generation. section 7.1.1 section 19.3
Use reusable schemas under components.schemas for resource models, then reference or combine them in operation inputs and outputs. This replaces spreadsheet-based modeling with an artifact that tools can read, validate, and reuse. section 7.1 section 7.8
Build a schema from the data shape outward:
- Set type to object, array, string, number, integer, or boolean. section 7.4.1 section 7.8
- Describe object members under properties, giving each property its own schema. section 7.4.3
- Mark mandatory object members by listing their names in required. section 7.8
- Describe arrays with items, whose value is the schema of each element. section 7.4.5
- Add descriptions, formats, ranges, lengths, patterns, enumerations, defaults, and examples when greater precision helps consumers or tools. section 7.4.3 section 19.3
A Product schema in OpenAPI YAML
components: schemas: Product: type: object properties: productReference: type: integer description: Unique identifier price: type: number description: Price in USD dateAdded: type: string format: date keywords: type: array items: type: string The same schema can support a reusable resource model, while an operation parameter can use an inline integer schema or reference part of the model. Use $ref to avoid duplicated request and response definitions. section 7.4.3 section 7.4.5 section 7.6.1 section 7.8
Start with essential types and descriptions while modeling, then add precision in a later pass. This keeps early design focused on identifying data while enabling documentation, testing, mocking, and code generation to use stronger constraints. section 7.1.3 section 19.3
Schemas also describe non-body parameters and response headers. Applying precise schemas to error responses can constrain fields and patterns, helping prevent improper formats and sensitive information leaks. section 7.6.1 section 12.10.5
Figure 7.1 Using a spreadsheet for the data models of our API was only to simplify our learning. We can describe data models with JSON Schema in our OpenAPI document once we start designing them.
Use this figure to connect spreadsheet-based data modeling with its replacement: JSON Schema embedded in the OpenAPI document. section 7.1
