Learn / JSON / Schema & Validation
Lesson 5 of 6

Schema & Validation

"Valid JSON" and "the JSON I actually need" are two different things. A document can be perfectly well-formed JSON syntax and still be missing a required field, have a number where you expected a string, or nest something one level too deep. JSON Schema is a way to describe the shape you expect, so you can catch bad data before your code tries to use it.

💡 The Bottom Line

Being syntactically valid JSON says nothing about whether the data is correct for your purposes. JSON Schema lets you declare required fields, expected types, and constraints (like a number range or a string pattern) as JSON itself, and validate incoming data against that declaration automatically instead of writing manual if-checks everywhere.

A simple schema

{
  "type": "object",
  "required": ["name", "age"],
  "properties": {
    "name": { "type": "string" },
    "age":  { "type": "number", "minimum": 0 },
    "email": { "type": "string", "format": "email" }
  }
}

This schema says: the data must be an object, it must have name and age keys (they're required), name must be a string, age must be a non-negative number, and if email is present, it must look like an email address. Anything not matching this shape fails validation — for example {"name": "Ada"} would fail because age is missing.

📋 What a schema can check that "is this valid JSON" can't

  • Required fields are actually present
  • A value's type matches what's expected (string vs number vs boolean)
  • Numeric ranges (minimum/maximum) and string patterns (via regex)
  • Array length constraints and whether array items must be unique
  • Whether extra, undeclared properties are allowed at all

Using it in practice

You don't usually write a validator by hand — you use a library that reads a JSON Schema document and checks arbitrary JSON data against it, returning a list of errors if it doesn't match. In JavaScript, libraries like ajv are common; in Python, jsonschema; in most languages, there's an established JSON Schema library already. This means the same schema document can validate data consistently across a whole system, even one written in multiple languages.

⚠️ Watch Out

A schema validates structure, not meaning. A schema can confirm that "age": 200 is a number within a declared range, but it can't tell you that 200 is an implausible human age unless you specifically set that as the maximum. Schema validation catches shape and type errors reliably — it's not a substitute for business-logic validation specific to your domain.

🙋 There Are No Dumb Questions

Q: Do I need a formal JSON Schema for every API I build?
A: Not necessarily for something small and internal — a few manual checks can be enough. But for any API with external consumers, or a team larger than one person, a schema pays off quickly: it becomes documentation of the expected shape, a single source of truth multiple services can validate against, and it can even auto-generate client code or API documentation in some tooling.

🔧 Try It Yourself

Write a JSON Schema for a "blog post" object requiring a title (string), published (boolean), and a tags array where every item must be a string. Then write two example JSON documents — one that should pass validation, and one that should fail (missing a required field, or the wrong type somewhere) — and reason through why each one passes or fails.

✅ Quick Check

A document is syntactically valid JSON but is missing a field your API requires. What will catch this?

Last stop: the common mistakes that trip up even experienced developers working with JSON day to day.

← Back to
Next →