π The Machine-Readable Contract for Web APIs
In modern agile microservices and decoupled frontend architectures, testing individual fields with isolated assertion statements (e.g., verifying status === 200 or checking that a single property exists) creates an illusion of stability. If a backend service renames an attribute from studentId to id, casts a number into a string, or drops an essential array element, client applications will crash silently. JSON Schema serves as the official, machine-readable declarative standard for describing and validating JSON data formats. By formalizing contracts using standard specifications (from Draft-07 to Draft 2020-12), QA automation engineers can validate entire response structures, complex regex patterns, array constraints, and strict data types in a single execution step, establishing unbreakable quality gates.
JSON SCHEMA SPECIFICATION EVOLUTION & TOOLING COMPATIBILITY:
ββββββββββββββββ¬βββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββ¬βββββββββββββββββββββββ
β DRAFT / SPEC β CANONICAL $schema URI β KEY ARCHITECTURAL FEATURES β PRIMARY TOOL SUPPORT β
ββββββββββββββββΌβββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββΌβββββββββββββββββββββββ€
β Draft-04 β .../draft-04/schema# β id, definitions, basic types β Legacy Swagger 2.0 β
β Draft-07 β .../draft-07/schema# β if/then/else, readOnly/writeOnly β Postman, OpenAPI 3.0 β
β Draft 2019-09β .../2019-09/schema β $defs replaces definitions, $anchor β Ajv v8, Python jsons β
β Draft 2020-12β .../2020-12/schema β prefixItems replaces tuple items, dynamicβ OpenAPI 3.1, Modern β
β β β $recursiveRef alignment β Enterprise Gateways β
ββββββββββββββββ΄βββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββ΄βββββββββββββββββββββββ
CORE STRUCTURAL GRAMMAR ARCHITECTURE:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://nikita-infotech.com/schemas/student-profile.json",
"title": "StudentProfileContract",
"description": "Formal contract specification for enrolled students",
"type": "object",
"required": ["studentId", "fullName", "email", "status"],
"properties": { ... },
"additionalProperties": false
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://nikita-infotech.com/schemas/student-v1.json",
"type": "object",
"required": [
"studentId",
"fullName",
"email",
"age",
"gpa",
"isScholarshipHolder",
"enrolledCourses",
"metadata"
],
"properties": {
"studentId": {
"type": "string",
"pattern": "^STU-[0-9]{5}$",
"description": "Unique identifier formatted as STU- followed by 5 digits"
},
"fullName": {
"type": "string",
"minLength": 3,
"maxLength": 70
},
"email": {
"type": "string",
"format": "email"
},
"age": {
"type": "integer",
"minimum": 18,
"maximum": 65
},
"gpa": {
"type": "number",
"minimum": 0.0,
"maximum": 4.0
},
"isScholarshipHolder": {
"type": "boolean"
},
"accountStatus": {
"type": "string",
"enum": ["ACTIVE", "PROBATION", "SUSPENDED", "ALUMNI"]
},
"metadata": {
"type": "object",
"required": ["createdAt", "profileUrl"],
"properties": {
"createdAt": {
"type": "string",
"format": "date-time"
},
"profileUrl": {
"type": "string",
"format": "uri"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
uniqueItems), and modeling heterogeneous tuples using modern prefixItems.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
// 1. Homogeneous Array of Objects
"enrolledCourses": {
"type": "array",
"minItems": 1,
"maxItems": 6,
"uniqueItems": true,
"items": {
"type": "object",
"required": ["courseCode", "credits", "instructor"],
"properties": {
"courseCode": { "type": "string", "pattern": "^[A-Z]{3,4}-[0-9]{3}$" },
"credits": { "type": "integer", "minimum": 1, "maximum": 4 },
"instructor": { "type": "string" }
},
"additionalProperties": false
}
},
// 2. Tuple Validation via prefixItems (Draft 2020-12)
// Structure strictly enforces: [String (BatchId), Number (ProgressPercent), Boolean (Passed)]
"batchMilestoneTuple": {
"type": "array",
"prefixItems": [
{ "type": "string", "pattern": "^BTCH-[0-9]{4}$" },
{ "type": "number", "minimum": 0, "maximum": 100 },
{ "type": "boolean" }
],
"items": false // Forbids extra elements beyond the 3 declared tuple positions
}
}
}
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["paymentId", "amount", "paymentDetails"],
"properties": {
"paymentId": { "type": "string" },
"amount": { "type": "number", "minimum": 1.0 },
"paymentDetails": {
// Must match EXACTLY ONE of the defined payment schemas
"oneOf": [
{
"title": "UPI Payment Method",
"type": "object",
"required": ["methodType", "upiId"],
"properties": {
"methodType": { "const": "UPI" },
"upiId": { "type": "string", "pattern": "^[a-zA-Z0-9.\\-_]{2,49}@[a-zA-Z]{2,49}$" }
},
"additionalProperties": false
},
{
"title": "Credit Card Payment Method",
"type": "object",
"required": ["methodType", "cardNumberLast4", "cardNetwork"],
"properties": {
"methodType": { "const": "CARD" },
"cardNumberLast4": { "type": "string", "pattern": "^[0-9]{4}$" },
"cardNetwork": { "type": "string", "enum": ["VISA", "MASTERCARD", "RUPAY"] }
},
"additionalProperties": false
}
]
}
}
}
if, then, and else keywords.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["studentType", "identityNumber"],
"properties": {
"studentType": {
"type": "string",
"enum": ["DOMESTIC_INDIA", "INTERNATIONAL"]
},
"identityNumber": {
"type": "string"
},
"passportExpiry": {
"type": "string",
"format": "date"
}
},
// IF student is DOMESTIC_INDIA -> identityNumber MUST be 12-digit Aadhaar
// ELSE (INTERNATIONAL) -> identityNumber MUST be Passport and require passportExpiry
"if": {
"properties": { "studentType": { "const": "DOMESTIC_INDIA" } }
},
"then": {
"properties": {
"identityNumber": { "pattern": "^[0-9]{12}$", "description": "12-digit Aadhaar format" }
}
},
"else": {
"required": ["passportExpiry"],
"properties": {
"identityNumber": { "pattern": "^[A-Z0-9]{8,10}$", "description": "International Passport format" }
}
}
}
Ajv (Another JSON Schema Validator) to assert schema integrity with detailed error traces.
// 1. Ingest built-in Ajv library (Postman natively includes Ajv)
const Ajv = require('ajv');
const ajv = new Ajv({ allErrors: true, verbose: true });
require('ajv-formats')(ajv); // Enables formats like email, uri, date-time
// 2. Define target schema contract (or retrieve via pm.sendRequest / Collection Variables)
const enrollmentSchema = {
"type": "object",
"required": ["enrollmentId", "studentId", "status", "feePaid"],
"properties": {
"enrollmentId": { "type": "string", "pattern": "^ENR-[0-9]{5}$" },
"studentId": { "type": "string", "pattern": "^STU-[0-9]{5}$" },
"status": { "type": "string", "enum": ["CONFIRMED", "PENDING"] },
"feePaid": { "type": "number", "minimum": 0 },
"contactEmail": { "type": "string", "format": "email" }
},
"additionalProperties": false
};
// 3. Compile and execute validation against live API response body
const responseData = pm.response.json();
const validate = ajv.compile(enrollmentSchema);
const isValid = validate(responseData);
pm.test("Response body strictly satisfies enterprise JSON Schema contract", function () {
if (!isValid) {
console.error("Schema Violations Detected:", validate.errors);
// Format human-readable diagnostic error messages
const failureDetails = validate.errors.map(err =>
`${err.instancePath || 'root'} ${err.message} (${JSON.stringify(err.params)})`
).join("; ");
pm.expect(isValid, `Validation Failures: ${failureDetails}`).to.be.true;
} else {
pm.expect(isValid).to.be.true;
}
});
jsonschema library, enforcing Draft 2020-12 compliance and catching subtle schema regressions in Pytest.
import pytest
import requests
from jsonschema import Draft202012Validator, validate, ValidationError
# Shared canonical contract definition
STUDENT_CONTRACT_SCHEMA = {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "name", "enrolled", "courses"],
"properties": {
"id": { "type": "integer", "minimum": 1 },
"name": { "type": "string", "minLength": 2 },
"enrolled": { "type": "boolean" },
"courses": {
"type": "array",
"minItems": 1,
"items": { "type": "string" }
}
},
"additionalProperties": False
}
class TestSchemaValidationContracts:
def test_live_api_satisfies_schema_contract(self):
"""Validates that live endpoint response conforms to strict schema definitions."""
mock_api_response = {
"id": 101,
"name": "Nikita Sharma",
"enrolled": True,
"courses": ["Playwright Python", "Enterprise API Testing"]
}
# Check schema validity first
Draft202012Validator.check_schema(STUDENT_CONTRACT_SCHEMA)
# Instantiate validator
validator = Draft202012Validator(STUDENT_CONTRACT_SCHEMA)
errors = list(validator.iter_errors(mock_api_response))
assert len(errors) == 0, f"Schema Contract Violated: {[err.message for err in errors]}"
def test_schema_catches_type_and_extra_property_violations(self):
"""Asserts that corrupted payloads with incorrect types or unexpected properties fail."""
corrupted_payload = {
"id": "101", # Error: String instead of integer
"name": "N", # Error: Less than minLength (2)
"enrolled": "true", # Error: String instead of boolean
"courses": [], # Error: Empty array (minItems: 1)
"unauthorizedKey": "malicious" # Error: additionalProperties: False
}
validator = Draft202012Validator(STUDENT_CONTRACT_SCHEMA)
errors = sorted(validator.iter_errors(corrupted_payload), key=lambda e: e.path)
assert len(errors) >= 4
error_fields = [list(e.path)[0] for e in errors if e.path]
print(f"\n[+] Successfully Caught Deviations on Fields: {error_fields}")
assert "id" in error_fields
assert "name" in error_fields
assert "courses" in error_fields
json-schema-validator and classpath-located schema documents.
import io.restassured.RestAssured;
import io.restassured.http.ContentType;
import org.testng.annotations.Test;
import static io.restassured.RestAssured.given;
import static io.restassured.module.jsv.JsonSchemaValidator.matchesJsonSchemaInClasspath;
public class JsonSchemaRestAssuredTest {
private static final String BASE_URL = "https://api.nikita-infotech.com";
@Test
public void testStudentDetailsConformsToJsonSchema() {
// Reads 'student_schema_contract.json' from src/test/resources/
given()
.baseUri(BASE_URL)
.header("Authorization", "Bearer eyJhbGciOi...")
.accept(ContentType.JSON)
.when()
.get("/api/v1/students/STU-88219")
.then()
.statusCode(200)
.contentType(ContentType.JSON)
// Single-line full contract assertion:
.body(matchesJsonSchemaInClasspath("student_schema_contract.json"));
}
}
$defs and $ref.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://nikita-infotech.com/schemas/corporate-order.json",
"type": "object",
"required": ["orderId", "billingAddress", "shippingAddress", "totalAmount"],
"properties": {
"orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
// Reusable References to Canonical Sub-Schemas:
"billingAddress": { "$ref": "#/$defs/PostalAddress" },
"shippingAddress": { "$ref": "#/$defs/PostalAddress" },
"totalAmount": { "$ref": "#/$defs/MonetaryAmount" }
},
// Centralized Domain Definitions Store ($defs):
"$defs": {
"PostalAddress": {
"type": "object",
"required": ["street", "city", "postalCode", "countryCode"],
"properties": {
"street": { "type": "string" },
"city": { "type": "string" },
"postalCode": { "type": "string", "pattern": "^[0-9]{6}$" },
"countryCode": { "type": "string", "enum": ["IN", "US", "UK", "DE"] }
},
"additionalProperties": false
},
"MonetaryAmount": {
"type": "object",
"required": ["currency", "value"],
"properties": {
"currency": { "type": "string", "enum": ["INR", "USD", "EUR"] },
"value": { "type": "number", "minimum": 0.01 }
},
"additionalProperties": false
}
}
}
JSON SCHEMA VALIDATION KEYWORDS REFERENCE:
βββββββββββββββββββββββ¬βββββββββββββββββββββββββββββ¬βββββββββββββββββββββββββββββββββββββββββββββββββββββ
β KEYWORD β APPLICABLE TYPE β VALIDATION BEHAVIOR / PURPOSE β
βββββββββββββββββββββββΌβββββββββββββββββββββββββββββΌβββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β type β All β Primitive: string, number, integer, boolean, β
β β β object, array, null β
β required β Object β Array of property names that MUST exist β
β properties β Object β Map defining validation schemas per property β
β additionalPropertiesβ Object β Boolean/Schema: Controls undeclared keys β
β minLength / maxLengthβ String β Validates string character length boundaries β
β pattern β String β ECMA-262 Regular Expression constraint β
β format β String β Semantic formats: email, uri, date-time, uuid β
β minimum / maximum β Number / Integer β Inclusive numeric value boundaries β
β exclusiveMin/Max β Number / Integer β Strict boundary limit (> or <) β
β minItems / maxItems β Array β Validates total item count boundaries in arrays β
β uniqueItems β Array β Boolean: Enforces that all array items are distinctβ
β enum β All β Array of exact acceptable literal values β
β const β All β Enforces exact scalar equality β
β $ref / $defs β All β Encapsulates and references reusable sub-schemas β
βββββββββββββββββββββββ΄βββββββββββββββββββββββββββββ΄βββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β TOP 5 JSON SCHEMA TESTING RULES: β
β 1. Always set additionalProperties: false to prevent unexpected or leaking properties. β
β 2. Test negative invalid payloads to verify that the schema validator catches every deviation. β
β 3. Use format keywords (email, date-time, uuid) instead of writing complex custom regex strings. β
β 4. Store schema contracts as standalone .json files in Git to share between frontend and QA teams. β
β 5. Validate schemas in CI/CD pipeline gates before running extensive functional test suites. β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ