liveBook · Manning

JSON Schema

As explained in The Design of Web APIs, Second Edition

A JSON Schema format is an annotation identifying an expected semantic representation for a value of a specified JSON data type.

JSON Schema describes and can validate JSON or YAML data. It works independently, but OpenAPI uses it to define the data carried by HTTP operations. A schema can specify what data is allowed and annotate it with descriptions that help people understand it. section 7.1.1 section 7.0

Start describing data as you design it. Define a complete resource model under `components.schemas`, then use its properties or derived models for operation inputs and outputs. This replaces separate data-model tables with schemas in the OpenAPI document. section 7.1.3 section 7.4

A product model and path parameter

A product can be an object with an identifier and an array of search keywords. The object's `required` list identifies mandatory properties; the array's `items` schema describes each element. A path parameter can have its own inline schema. ```yaml components: schemas: Product: type: object required: [productReference] properties: productReference: type: integer description: Unique identifier keywords: type: array items: type: string paths: /products/{productReference}: parameters: - name: productReference in: path required: true schema: type: integer ``` Keep the parameter's type consistent with the resource property it identifies. section 7.4.3 section 7.4.5 section 7.6.1 section 7.8

Put an inline schema in an operation's parameter or response-header `schema` property when the data is local to that use. Reference a reusable schema with `$ref` when request or response bodies share a model; this avoids duplication and unwanted differences. A `Location` response header, for example, can use an ad hoc `type: string` schema. section 7.6.1 section 7.6.3 section 7.8

Add precision when it serves a purpose. Keywords can express number ranges, array sizes, string patterns, enumerations, and defaults for documentation, code generation, testing, or mocking. For a 500 error, `const` and `pattern` can constrain expected error fields and help prevent sensitive details from appearing—provided the implementation follows the contract. section 19.3 section 12.10.5

Check the tools before relying on advanced features: OpenAPI 3.0 and 3.1 use different JSON Schema versions, and tool support may vary. An API gateway can validate requests against schemas, but doing so before the implementation handles them may prevent more exhaustive, user-friendly errors. Model the essential data first; add finer constraints in a later pass if needed. section 7.2 section 19.1.5 section 19.3

How The Design of Web APIs, Second Edition covers it

How deep it goes
Works through types, properties, required fields, arrays, references, and selected constraints; defers less common keywords to reference documentation.
Examples
Uses a product resource, an inline product identifier parameter, a Location header, and a constrained 500-error response.
What it assumes
Assumes familiarity with authoring OpenAPI documents while introducing the JSON Schema essentials needed to model API data.
What you can do after
Build it from scratch in OpenAPI using reusable resource schemas, inline operation schemas, and references where models are shared.
How it connects
Connects OpenAPI, HTTP parameters and responses, resource models, API security, and code generation.

Also explained in

Compare how 4 books explain JSON Schema →

Related concepts

This explainer was generated by Manning's knowledge graph from the text of The Design of Web APIs, Second Edition. The section links point to the parts of the book it draws on.