What You'll Learn
- The difference between status code validation and schema validation
- How to use JSON Schema to validate responses
- How to write assertions for response structure and values
- How to catch silent API changes that break clients
Why This Matters
An API that returns 200 OK with the wrong data is worse than one that returns 500. The 200 tricks you into thinking everything is fine. Schema validation catches this — it verifies the response has the right fields, the right types, and the right structure. Without it, your tests give false confidence.
Three Layers of Response Validation
| Layer | What it checks | Example |
|---|---|---|
| Status code | The HTTP status | 200, 201, 404 |
| Schema | Structure — fields, types, required vs optional | "id is a number, name is a string" |
| Value | Specific values | "name equals 'Anita'" |
All three are necessary. Status-only validation misses data bugs. Value-only validation misses structural changes. Schema-only validation misses logic bugs.
Status Code Validation
// JavaScript (Jest-style)
expect(response.status).toBe(201);
// Postman test
pm.test("Status is 201", function () {
pm.response.to.have.status(201);
});
Schema Validation — Manual Approach
The simplest way to validate structure is to check each field:
const body = response.body;
// Check structure
expect(typeof body.id).toBe("number");
expect(typeof body.name).toBe("string");
expect(typeof body.email).toBe("string");
expect(typeof body.created_at).toBe("string");
// Check required fields are present
expect(body.id).toBeDefined();
expect(body.name).toBeDefined();
// Check specific values
expect(body.name).toBe("Anita");
expect(body.email).toBe("anita@example.com");
This works but is verbose. For complex responses, use JSON Schema.
Schema Validation — JSON Schema
JSON Schema is a vocabulary for describing JSON structures. You define the expected shape once, then validate any response against it.
Example schema for a User
{
"type": "object",
"required": ["id", "name", "email"],
"properties": {
"id": {"type": "number"},
"name": {"type": "string", "minLength": 1, "maxLength": 100},
"email": {"type": "string", "format": "email"},
"age": {"type": "number", "minimum": 0, "maximum": 150},
"created_at": {"type": "string", "format": "date-time"},
"roles": {
"type": "array",
"items": {"type": "string"}
},
"address": {
"type": "object",
"properties": {
"city": {"type": "string"},
"country": {"type": "string"}
}
}
},
"additionalProperties": false
}
Validating a response against the schema
// JavaScript using Ajv (Another JSON Validator)
const Ajv = require("ajv");
const ajv = new Ajv();
const validate = ajv.compile(userSchema);
const valid = validate(response.body);
if (!valid) {
console.error("Schema validation failed:", validate.errors);
}
What JSON Schema catches
- Missing required fields
- Wrong types (string vs number)
- Out-of-range values (negative age)
- Malformed emails and dates
- Unexpected extra fields (with
additionalProperties: false) - Array element types
- Nested object structure
Postman Schema Validation
Postman has built-in JSON Schema support:
// In the Tests tab of a request
const userSchema = {
type: "object",
required: ["id", "name", "email"],
properties: {
id: {type: "number"},
name: {type: "string"},
email: {type: "string"}
}
};
pm.test("Response matches User schema", function () {
pm.response.to.have.jsonSchema(userSchema);
});
Postman shows a green check if the response matches, red if not.
Common Schema Validation Pitfalls
1. Forgetting additionalProperties: false
Without this, the schema accepts any extra fields. You will not catch the API silently adding is_admin: true to user responses.
2. Allowing null where an object is expected
"address": {"type": "object"}
If address can be null, you need:
"address": {"type": ["object", "null"]}
Or use oneOf with explicit null handling.
3. Not validating array item types
"roles": {"type": "array"}
This accepts [1, 2, 3] — an array of numbers. Specify items:
"roles": {"type": "array", "items": {"type": "string"}}
4. Treating optional and required the same
If a field is optional, do not put it in required. But still specify its type in properties so when it is present, it has the right type.
5. Not handling the empty array case
"tags": {"type": "array", "minItems": 1}
If tags can be empty, remove minItems: 1. If it cannot, test with an empty array to verify the API rejects it.
Value Validation
Beyond schema, validate specific values when they matter:
// The created user's name should match what we sent
expect(body.name).toBe(requestBody.name);
// The ID should be a positive integer
expect(body.id).toBeGreaterThan(0);
expect(Number.isInteger(body.id)).toBe(true);
// The created_at should be within the last minute
const oneMinuteAgo = Date.now() - 60_000;
expect(new Date(body.created_at).getTime()).toBeGreaterThan(oneMinuteAgo);
Response Header Validation
Don't forget headers — they often carry important information:
// 201 should have a Location header
expect(response.headers.location).toBeDefined();
// Content-Type should be JSON
expect(response.headers["content-type"]).toContain("application/json");
// Cache-Control should be set for cacheable endpoints
expect(response.headers["cache-control"]).toBeDefined();
Common Mistakes
- Validating only the status code. 200 with wrong data is a silent failure.
- Validating only specific values. A new field added by the API goes unnoticed.
- Not using
additionalProperties: false. Silent API changes go undetected. - Not validating arrays of objects. An array with one malformed item passes shallow checks.
- Validating the schema but not the values. Schema says "name is a string" but the name is wrong. Both matter.
- Not validating error responses. Errors should also follow a schema — consistent format matters.
Practical Exercise (15 minutes)
- Pick a GET endpoint on JSONPlaceholder.
- Write a JSON Schema for the expected response.
- Validate the actual response against the schema (use ajv in Node.js or Postman's
jsonSchema). - Now break the schema (e.g., require a field that does not exist) and verify the validation fails.
Mini Challenge
For any API you test regularly, write JSON Schemas for the 3 most important endpoints. Run them as part of your test suite. Did you find any responses that don't match the documented schema? Most APIs have at least one mismatch.
Key Takeaways
- Three layers of validation: status code, schema, value. All three are necessary.
- JSON Schema describes the expected structure. Use it to validate responses automatically.
- Always set
additionalProperties: falseto catch silent API changes. - Validate array item types, nullable fields, and error response formats — not just success responses.
- Headers matter too — check Content-Type, Location, Cache-Control where relevant.
Previously: Lesson 34 covered boundary testing.
Today: You learned to validate the structure of responses, not just the status code.
Next: Lesson 36 covers contract testing and integration testing.
FAQ
What is the difference between schema validation and contract testing?
Schema validation checks that a single response matches its schema. Contract testing checks that the consumer and provider agree on the contract — both sides are tested. Contract testing is broader: it ensures the provider's responses match what the consumer expects, and vice versa.
Should I use JSON Schema or TypeScript types?
Both. TypeScript types protect you at compile time (in your own code). JSON Schema protects you at runtime (validating actual API responses). They complement each other. Many tools can generate one from the other.
Comments
Comments
Post a Comment