JSON SCHEMA VALIDATION & CONTRACT TESTING

Master contract testing and structural payload verification in Playwright with Python: combining APIRequestContext with jsonschema and Pydantic, enforcing JSON Schema Draft 7/2020-12 rules, type constraints, format validators, regex patterns, nested arrays, and defensive error reporting.

📐 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.

1. Schema Contract Architecture & Draft Specifications
JSON Schema is an IETF standard that provides a blueprint for JSON data structures. It defines mandatory properties, primitive data types, string constraints, and nested schemas.
JSON Schema Architectural Blueprint
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
Architectural Value: Detect breaking backend API changes before they reach user-facing frontend components, ensuring true consumer-driven contract testing.
Real-Time Example 1: Basic Schema Validation with jsonschema.validate()
Fetch an API response with Playwright's api.get() and validate its structure against a basic JSON Schema using the Python jsonschema library.
Python (jsonschema.validate Implementation)
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()
Output: Contract Test Passed: Payload matches user_profile_schema perfectly!
Real-Time Example 2: Strict Format Validation (Email, UUID, Date-Time & URI)
Enforce semantic string formatting rules using the format keyword (supported formats include email, date-time, uuid, and uri) via format_checker.
Python (Semantic Format Validation)
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()
Output: Format Validation Successful: UUID Verified : f47ac10b-58cc-4372-a567-0e02b2c3d479 Email Verified : ops@nikita-infotech.com Date-Time Verified : 2026-10-29T13:46:00Z
Real-Time Example 3: Nested Objects & Repeating Array Collections
Validate enterprise data structures containing nested parent-child dictionaries and array lists of repeating items with minimum, maximum, and uniqueness constraints.
Python (Nested Array Collection Schema)
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()
Output: Complex Nested Schema Validation Passed: Order ID : ORD-4491 City : Pune Items Count : 2
Real-Time Example 4: Catching Contract Violations & Reporting Errors
Capture and inspect jsonschema.ValidationError exceptions when an endpoint returns unexpected data types or omitted required fields, printing actionable failure diagnostics.
Python (Contract Failure Handling)
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()
Output: Caught Contract Drift Exception: Failed Property : ['port'] Violation Rule : type Diagnostic Msg : '8080' is not of type 'integer'
Real-Time Example 5: Schema Validation with Pydantic Data Models
Combine Playwright's api.get() with Pydantic models to enforce type validation, automatic type casting, and schema integrity through Pythonic class definitions.
Python (Pydantic Model Validation)
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()
Output: Pydantic Contract Validation Succeeded: Employee ID : 1042 Full Name : Rahul Sharma Verified Email: rahul.sharma@nikita-infotech.com Skills List : ['Playwright', 'Python', 'Docker']
Real-Time Example 6: External JSON Schema File Hydration
Load schema contracts from dedicated .json specification files located in a test fixtures repository to decouple test logic from schema definitions.
Python (External Schema File Loader)
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)
Output: Successfully loaded and validated against external schema file: '/tmp/customer_schema.json'
Real-Time Example 7: Validating Dynamic Intercepted Network Responses
Intercept asynchronous background API calls triggered during browser UI interactions using page.expect_response() and validate the live payload against a JSON schema contract.
Python (Intercepted UI Network Response Schema Validation)
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()
Output: Intercepted UI network call honored schema contract! Unread: 3
Real-Time Example 8: Reusable Pytest Schema Validation Assertions
Package schema validation logic into a custom Pytest helper function or custom assertion fixture to standardize contract checking across your entire test suite.
Python (Pytest Custom Schema Assertion Helper)
# 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()
Output: Pytest contract assertion helper completed with zero violations!
Real-Time Example 9: JSON Schema Keywords & Types Reference Matrix
A comprehensive reference summary of JSON Schema validation keywords, data types, string formats, and numerical boundary constraints.
JSON Schema Reference Matrix
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.             │
└──────────────────────────────┴──────────────────────────────┴─────────────────────────────────────────────────────────┘
Engineering Best Practice: Store reusable JSON Schemas in version-controlled JSON files. Use additionalProperties: False to detect unintended schema drift or leaked internal fields in API responses.