📐 Why JSON Schema Validation & Contract Testing?
In modern agile and microservice architectures, backend engineering teams release updates independently of frontend web applications. While checking simple individual values (like assert response.json()["status"] == "ok") confirms basic data presence, it fails to guard against schema drift: renamed keys, unexpected null fields, altered date-time formats, or mismatched data types (such as an integer ID converting to a string). JSON Schema Validation defines a strict, declarative contract between client and server. By pairing Playwright's APIRequestContext with Python's jsonschema and pydantic libraries, test suites can validate every attribute, nested object, and data constraint across entire REST payloads in a single, resilient assertion.
CONTRACT VALIDATION TOPOLOGY:
┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. Playwright Dispatches Direct HTTP Request │
│ response = api.get("/api/v1/users/101") │
│ data = response.json() │
└─────────────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. Schema Validator Enforces Structural Contract │
│ jsonschema.validate(instance=data, schema=USER_SCHEMA) │
├─────────────────────────────────────────────────────────────────────────────┤
│ Core Constraint Checks: │
│ * "type": "object" | "array" | "string" | "number" | "integer" | "boolean" │
│ * "required": ["id", "username", "email", "roles"] │
│ * "properties": { ... field definitions & format rules ... } │
│ * "additionalProperties": False (Rejects unauthorized/undocumented keys) │
└─────────────────────────────────────────────────────────────────────────────┘
│
┌─────────────────────────────┴─────────────────────────────┐
▼ ▼
✅ VALID PAYLOAD ❌ CONTRACT DRIFT DETECTED
Contract Honored ValidationError Raised:
Tests Continue 'email' is not a valid email address
api.get() and validate its structure against a basic JSON Schema using the Python jsonschema library.
from playwright.sync_api import sync_playwright, expect
from jsonschema import validate, ValidationError
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
# 1. Define standard JSON Schema contract
user_profile_schema = {
"type": "object",
"properties": {
"user_id": {"type": "integer"},
"username": {"type": "string"},
"is_active": {"type": "boolean"},
"credit_balance": {"type": "number"}
},
"required": ["user_id", "username", "is_active", "credit_balance"],
"additionalProperties": False
}
# Simulated API response payload
simulated_payload = {
"user_id": 99214,
"username": "pooja_patil",
"is_active": True,
"credit_balance": 18450.75
}
# Dispatch request using Playwright
response = api.post("/post", data=simulated_payload)
expect(response).to_be_ok()
response_data = response.json()["json"]
# 2. Validate response against contract
try:
validate(instance=response_data, schema=user_profile_schema)
print("Contract Test Passed: Payload matches user_profile_schema perfectly!")
except ValidationError as err:
print(f"Contract Violation: {err.message}")
api.dispose()
format keyword (supported formats include email, date-time, uuid, and uri) via format_checker.
from playwright.sync_api import sync_playwright, expect
from jsonschema import validate, FormatChecker
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
# Schema with strict format constraints
account_contract = {
"type": "object",
"properties": {
"account_uuid": {"type": "string", "format": "uuid"},
"support_email": {"type": "string", "format": "email"},
"documentation_url": {"type": "string", "format": "uri"},
"registered_at": {"type": "string", "format": "date-time"}
},
"required": ["account_uuid", "support_email", "documentation_url", "registered_at"]
}
test_payload = {
"account_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"support_email": "ops@nikita-infotech.com",
"documentation_url": "https://nikita-infotech.com/docs",
"registered_at": "2026-10-29T13:46:00Z"
}
response = api.post("/post", data=test_payload)
expect(response).to_be_ok()
returned_json = response.json()["json"]
# Validate with FormatChecker enabled
validate(
instance=returned_json,
schema=account_contract,
format_checker=FormatChecker()
)
print("Format Validation Successful:")
print(f" UUID Verified : {returned_json['account_uuid']}")
print(f" Email Verified : {returned_json['support_email']}")
print(f" Date-Time Verified : {returned_json['registered_at']}")
api.dispose()
from playwright.sync_api import sync_playwright, expect
from jsonschema import validate
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
# Schema defining order with multiple nested order line items
order_invoice_schema = {
"type": "object",
"properties": {
"order_id": {"type": "string", "pattern": r"^ORD-\d{4}$"},
"billing_address": {
"type": "object",
"properties": {
"city": {"type": "string"},
"postal_code": {"type": "string", "pattern": r"^\d{6}$"}
},
"required": ["city", "postal_code"]
},
"line_items": {
"type": "array",
"minItems": 1,
"uniqueItems": True,
"items": {
"type": "object",
"properties": {
"sku": {"type": "string"},
"qty": {"type": "integer", "minimum": 1},
"rate": {"type": "number", "exclusiveMinimum": 0}
},
"required": ["sku", "qty", "rate"]
}
}
},
"required": ["order_id", "billing_address", "line_items"]
}
order_data = {
"order_id": "ORD-4491",
"billing_address": {"city": "Pune", "postal_code": "411014"},
"line_items": [
{"sku": "SKU-OPTIC-1", "qty": 2, "rate": 1499.50},
{"sku": "SKU-RELAY-9", "qty": 1, "rate": 3200.00}
]
}
response = api.post("/post", data=order_data)
expect(response).to_be_ok()
validate(instance=response.json()["json"], schema=order_invoice_schema)
print("Complex Nested Schema Validation Passed:")
print(f" Order ID : {order_data['order_id']}")
print(f" City : {order_data['billing_address']['city']}")
print(f" Items Count : {len(order_data['line_items'])}")
api.dispose()
jsonschema.ValidationError exceptions when an endpoint returns unexpected data types or omitted required fields, printing actionable failure diagnostics.
from playwright.sync_api import sync_playwright
from jsonschema import validate, ValidationError
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
schema = {
"type": "object",
"properties": {
"service_id": {"type": "string"},
"port": {"type": "integer", "minimum": 1, "maximum": 65535}
},
"required": ["service_id", "port"]
}
# Deliberate contract drift: 'port' returned as string instead of integer
corrupted_backend_response = {
"service_id": "SVC_AUTH_GATEWAY",
"port": "8080" # Invalid! String violates integer type requirement
}
try:
validate(instance=corrupted_backend_response, schema=schema)
except ValidationError as error:
print("Caught Contract Drift Exception:")
print(f" Failed Property : {list(error.path)}")
print(f" Violation Rule : {error.validator}")
print(f" Diagnostic Msg : {error.message}")
api.dispose()
api.get() with Pydantic models to enforce type validation, automatic type casting, and schema integrity through Pythonic class definitions.
from typing import List, Optional
from pydantic import BaseModel, EmailStr, Field
from playwright.sync_api import sync_playwright, expect
# Define Pydantic Schema Model
class EmployeeRecord(BaseModel):
emp_id: int = Field(gt=0)
name: str = Field(min_length=2)
email: EmailStr
skills: List[str]
is_admin: Optional[bool] = False
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
payload = {
"emp_id": 1042,
"name": "Rahul Sharma",
"email": "rahul.sharma@nikita-infotech.com",
"skills": ["Playwright", "Python", "Docker"],
"is_admin": True
}
response = api.post("/post", data=payload)
expect(response).to_be_ok()
# Parse and validate response JSON using Pydantic
employee = EmployeeRecord(**response.json()["json"])
print("Pydantic Contract Validation Succeeded:")
print(f" Employee ID : {employee.emp_id}")
print(f" Full Name : {employee.name}")
print(f" Verified Email: {employee.email}")
print(f" Skills List : {employee.skills}")
api.dispose()
.json specification files located in a test fixtures repository to decouple test logic from schema definitions.
import os
import json
import tempfile
from playwright.sync_api import sync_playwright, expect
from jsonschema import validate
# Create temporary schema contract on disk (schemas/customer_schema.json)
temp_dir = tempfile.gettempdir()
schema_file_path = os.path.join(temp_dir, "customer_schema.json")
with open(schema_file_path, "w") as f:
json.dump({
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"customer_id": {"type": "integer"},
"tier": {"type": "string", "enum": ["Standard", "Professional", "Enterprise"]}
},
"required": ["customer_id", "tier"]
}, f)
with sync_playwright() as p:
api = p.request.new_context(base_url="https://httpbin.org")
response = api.post("/post", data={"customer_id": 5501, "tier": "Enterprise"})
expect(response).to_be_ok()
# Load contract from external JSON file
with open(schema_file_path, "r") as sf:
external_schema = json.load(sf)
validate(instance=response.json()["json"], schema=external_schema)
print(f"Successfully loaded and validated against external schema file: '{schema_file_path}'")
api.dispose()
if os.path.exists(schema_file_path):
os.remove(schema_file_path)
page.expect_response() and validate the live payload against a JSON schema contract.
from playwright.sync_api import sync_playwright, expect
from jsonschema import validate
with sync_playwright() as p:
browser = p.chromium.launch(headless=True)
page = browser.new_page()
# Define contract for background notification payload
notification_schema = {
"type": "object",
"properties": {
"unread_count": {"type": "integer", "minimum": 0},
"alerts": {"type": "array", "items": {"type": "string"}}
},
"required": ["unread_count", "alerts"]
}
# Web page that dispatches background fetch call
page.set_content("""
0
""")
# Mock endpoint and return JSON matching contract
page.route("**/api/alerts", lambda route: route.fulfill(
status=200,
json={"unread_count": 3, "alerts": ["Disk 90% Full", "New User Created", "Backup Done"]}
))
# Synchronize on network response and validate schema
with page.expect_response("**/api/alerts") as resp_info:
page.locator("#check-alerts").click()
api_response = resp_info.value
validate(instance=api_response.json(), schema=notification_schema)
print(f"Intercepted UI network call honored schema contract! Unread: {api_response.json()['unread_count']}")
browser.close()
# content of conftest.py
import pytest
from jsonschema import validate, ValidationError, FormatChecker
from playwright.sync_api import APIResponse
def assert_matches_schema(response: APIResponse, schema: dict):
"""Custom assertion helper for validating Playwright API responses against a JSON Schema."""
assert response.ok, f"API Request failed with HTTP {response.status}: {response.text()}"
payload = response.json()
try:
validate(instance=payload, schema=schema, format_checker=FormatChecker())
except ValidationError as err:
pytest.fail(f"Contract Schema Drift Detected at {list(err.path)}: {err.message}")
# content of test_catalog_contract.py
CATALOG_SCHEMA = {
"type": "object",
"properties": {
"status": {"type": "string", "enum": ["ACTIVE", "MAINTENANCE"]},
"version": {"type": "string"}
},
"required": ["status", "version"]
}
def test_api_contract_compliance(playwright):
api = playwright.request.new_context(base_url="https://httpbin.org")
response = api.post("/post", data={"status": "ACTIVE", "version": "v3.2.1"})
# Extract JSON body from httpbin wrapper
extracted_response_stub = type('Obj', (object,), {
'ok': response.ok,
'status': response.status,
'json': lambda: response.json()["json"],
'text': response.text
})
assert_matches_schema(extracted_response_stub, CATALOG_SCHEMA)
print("Pytest contract assertion helper completed with zero violations!")
api.dispose()
JSON SCHEMA KEYWORDS & CONSTRAINTS MATRIX:
┌──────────────────────────────┬──────────────────────────────┬─────────────────────────────────────────────────────────┐
│ Keyword / Property │ Value Types / Formats │ Primary Description / Use Case │
├──────────────────────────────┼──────────────────────────────┼─────────────────────────────────────────────────────────┤
│ "type" │ "string", "number", "integer"│ Defines required data type for property. │
│ │ "boolean", "array", "object" │ Can accept list of types (e.g. ["string", "null"]). │
│ "required" │ List[str] │ Array of keys that must be present in the object. │
│ "additionalProperties" │ bool │ False rejects undocumented extra keys in the object. │
│ "properties" │ Dict[str, Schema] │ Dictionary specifying schemas for object keys. │
│ "items" │ Schema Object │ Schema applied to every element in an array. │
│ "minItems" / "maxItems" │ int │ Minimum and maximum permitted array length. │
│ "uniqueItems" │ bool │ When True, enforces all array items must be unique. │
│ "minimum" / "maximum" │ int / float │ Inclusive numeric range boundaries. │
│ "exclusiveMinimum" / "Max" │ int / float │ Strict numeric inequality boundaries (value > N). │
│ "pattern" │ str (Regex) │ Enforces string pattern (e.g. r"^ORD-\d+$"). │
│ "enum" │ List[Any] │ Restricts value to an exact set of allowed choices. │
│ "format" │ "email", "uuid", "date-time" │ Validates semantic string formatting rules. │
│ │ "uri", "ipv4", "ipv6", "time"│ Requires FormatChecker() during validation. │
└──────────────────────────────┴──────────────────────────────┴─────────────────────────────────────────────────────────┘