JSON Schema: Getting Started
The official step-by-step guide to JSON Schema, the standard vocabulary for describing and validating the shape of JSON data. API testers use schemas to check a whole response at once for required fields, types and allowed values, in Postman tests and in code, and this guide builds one up clearly from scratch.
Guide
Web Development
JSON Schema organisation
Beginner
Free
What it is
JSON Schema is a declarative language for describing the structure of JSON data: which properties an object must have, their types, allowed values, formats, array contents and how schemas reference each other. The official "Getting started step by step" guide builds a schema for a product catalogue from nothing, using the 2020-12 version of the specification.
What the guide covers
- Identifying a schema with $schema and $id, and annotating it with title and description.
- Constraining types with type, and describing objects with properties and required.
- Numeric constraints such as exclusiveMinimum.
- Arrays with items, minItems and uniqueItems.
- Nested objects, and splitting schemas into reusable pieces with $ref.
Why testers care
A single schema check validates the whole shape of an API response in one assertion: a renamed field, a number that became a string, a missing required property or an unexpected null all fail the check, where dozens of single-field assertions could miss one. Postman tests can validate a response against a schema, and code-based suites in JavaScript or Java use validator libraries or companion modules to do the same. Many APIs are described with OpenAPI, which uses JSON Schema for request and response bodies, so the skill transfers directly.
Is it worth your time?
Yes, if you test APIs. The getting started guide takes an hour or two, and you will use what it teaches in almost every API suite. Read the rest of the site's learning material when you need more advanced features such as conditional schemas.
Prerequisites
Comfort reading JSON. No programming is needed to write a schema, though you will use one from code or Postman scripts.
Free or paid?
Free. JSON Schema is an open specification with free documentation.
How to use it well
Write a schema for one Restful-booker response, make it strict enough to catch real changes, then deliberately break the response in a mock and confirm the check fails. Keep schemas in files in your repository rather than pasted into every test.
Common questions
Which draft should I use? Use the one your validator and tools support; the official guide uses 2020-12.
Is a schema check enough on its own? No. It checks shape, not business logic, so keep assertions on the values that matter.
Ready to start?
Opens on JSON Schema organisation in a new tab.
Stuck on something specific?
Writing only gets you so far. If you want an answer to your situation rather than the general case, book a session and we will work through it together. Sessions are free for approved Sefism members, and a few slots open each week.
Follow along
New writing, resources and project ideas land here first.