How I validate JSON with a schema before blaming the API

When an API receives JSON, it usually expects a certain shape. If one field is missing or one value has the wrong type, the request may fail.

A JSON Schema describes that expected shape.

The JSON Schema Validator lets you paste a JSON document and a schema, then see exactly which fields do not match.

The simple idea

JSON is the data:

{
  "name": "Ana",
  "age": 30
}

JSON Schema is the rulebook:

{
  "type": "object",
  "required": ["name", "age"],
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "number" }
  }
}

The validator checks whether the data follows the rulebook.

Step 1: start with the top-level type

Most API payloads are objects:

{
  "type": "object"
}

This means the JSON should look like:

{
  "key": "value"
}

not like:

[1, 2, 3]

or:

"hello"

Start with the top-level type before adding details.

Step 2: define properties

Properties describe fields inside an object.

{
  "type": "object",
  "properties": {
    "email": { "type": "string" },
    "age": { "type": "number" }
  }
}

This says:

• email should be a string;
• age should be a number.

It does not yet say those fields are required.

Step 3: mark required fields

Use required to say which fields must exist:

{
  "type": "object",
  "required": ["email"],
  "properties": {
    "email": { "type": "string" },
    "age": { "type": "number" }
  }
}

Now this is valid:

{
  "email": "ana@example.com"
}

But this is not:

{
  "age": 30
}

because email is missing.

Step 4: check strings, numbers, booleans, and null

Common schema types:

string
number
integer
boolean
object
array
null

Be careful with numbers stored as strings.

This JSON value is a number:

10000

This one is a string:

"10000"

Some APIs require amounts as strings to preserve formatting. Others require numbers. The schema should match the API contract.

Step 5: validate nested objects

Nested objects need nested rules.

Payload:

{
  "user": {
    "name": "Ana",
    "email": "ana@example.com"
  }
}

Schema:

{
  "type": "object",
  "required": ["user"],
  "properties": {
    "user": {
      "type": "object",
      "required": ["name", "email"],
      "properties": {
        "name": { "type": "string" },
        "email": { "type": "string" }
      }
    }
  }
}

The structure of the schema follows the structure of the JSON.

Step 6: validate arrays

For arrays, define the item shape.

Payload:

{
  "items": [
    { "sku": "A1", "qty": 2 },
    { "sku": "B2", "qty": 1 }
  ]
}

Schema:

{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["sku", "qty"],
        "properties": {
          "sku": { "type": "string" },
          "qty": { "type": "integer" }
        }
      }
    }
  }
}

This checks every item in the array.

Step 7: read the error path

A good validator tells you where the problem is.

An error path may look like:

/items/0/qty

Plain meaning:

• go to items;
• take item 0, the first item;
• check qty.

If the error says that value should be an integer, you know exactly which field to fix.

The JSON Schema Validator shows these paths so you do not have to search the whole document manually.

Step 8: use schema for API debugging

When an API rejects a payload, I check:

1. Is the JSON valid?
2. Does it match the schema?
3. Are required fields present?
4. Are values the right types?
5. Are nested objects in the expected place?
6. Are arrays using the expected item shape?

This separates two problems:

• invalid JSON syntax;
• valid JSON with the wrong shape.

Those are different bugs.

Step 9: keep the schema close to examples

A schema is easier to trust when it sits next to example payloads.

For documentation, I like having:

• one valid example;
• one invalid example;
• the schema;
• notes for required and optional fields.

This helps frontend, backend, and QA people talk about the same contract.

My JSON Schema checklist

When writing or testing a schema, I check:

1. What is the top-level type?
2. Which fields are required?
3. What type should each field be?
4. Are nested objects described?
5. Are arrays and their items described?
6. Are numbers and strings used intentionally?
7. Does the validator show clear error paths?
8. Does the schema match the API documentation?

JSON Schema is not only for strict validation. It is also a way to make an API contract visible and testable.