Validate data with schemas

Recipe

This recipe shows how to validate data structures using Zod (TypeScript) or Pydantic (Python), including synchronous and asynchronous validation patterns.

TypeScript: Zod version 3.22+ is supported, which provides the zod/v3 export path required by libraries like json-schema-to-zod. Python: Examples target Pydantic v2 (pydantic>=2.0).

Code example

Synchronous validation

TypeScript

import { z } from "zod";

// Define the Contract schema
const ContractSchema = z.object({
  contractId: z.string().uuid("Invalid contract ID format"),
  clientName: z.string().min(1, "Client name is required"),
  contractValue: z.number().min(0, "Contract value must be non-negative"),
  status: z.union([
    z.literal("active"),
    z.literal("completed"),
    z.literal("terminated"),
  ]),
  startDate: z.string().datetime("Invalid start date format"),
  endDate: z.string().datetime("Invalid end date format").optional(),
});

// Infer TypeScript type from schema
type Contract = z.infer<typeof ContractSchema>;

// Example data
const validContract = {
  contractId: "550e8400-e29b-41d4-a716-446655440000",
  clientName: "Client X",
  contractValue: 50000,
  status: "active" as const,
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-12-31T23:59:59Z",
};

const invalidContract = {
  contractId: "invalid-uuid",
  clientName: "",
  contractValue: -1000, // invalid: negative value
  status: "active" as const,
  startDate: "2024-01-01T00:00:00Z",
};

// Synchronous validation with safeParse()

const result1 = ContractSchema.safeParse(validContract);
if (!result1.success) {
  console.error("Validation errors:", result1.error.format());
} else {
  console.log("✓ Valid contract:", result1.data);
}

// Handling validation errors
const result2 = ContractSchema.safeParse(invalidContract);
if (!result2.success) {
  console.error("Validation errors:", result2.error.format());
} else {
  console.log("Valid contract:", result2.data);
}

// Alternative: parse() method (throws on error)
try {
  const validated = ContractSchema.parse(validContract);
  console.log("\n✓ Parsed successfully:", validated);
} catch (error) {
  if (error instanceof z.ZodError) {
    console.error("Validation failed:", error.issues);
  }
}

from pydantic import BaseModel, Field, ValidationError
from typing import Literal, Optional
from datetime import datetime


# Define the Contract model
class Contract(BaseModel):
    contract_id: str
    client_name: str = Field(min_length=1, description="Client name is required")
    contract_value: float = Field(ge=0, description="Must be non-negative")
    status: Literal["active", "completed", "terminated"]
    start_date: datetime
    end_date: Optional[datetime] = None


# Example data
valid_contract = {
    "contract_id": "550e8400",
    "client_name": "Client X",
    "contract_value": 50000,
    "status": "active",
    "start_date": "2024-01-01T00:00:00Z",
    "end_date": "2024-12-31T23:59:59Z",
}

invalid_contract = {
    "contract_id": "invalid-uuid",
    "client_name": "",
    "contract_value": -1000,  # invalid: negative value
    "status": "active",
    "start_date": "2024-01-01T00:00:00Z",
}

# Validate with model_validate() — raises ValidationError on failure
try:
    contract = Contract.model_validate(valid_contract)
    print("✓ Valid contract:", contract)
except ValidationError as e:
    print("Validation errors:", e.errors())

# Handling validation errors
try:
    contract = Contract.model_validate(invalid_contract)
except ValidationError as e:
    for error in e.errors():
        print(f"  - {error['loc']}: {error['msg']}")

# Alternative: model_construct() skips validation (use only for trusted data)
trusted = Contract.model_construct(**valid_contract)
print("\n✓ Constructed without validation:", trusted)

Asynchronous validation

TypeScript

import { z } from "zod";

const asyncContract = {
  contractId: "550e8400-e29b-41d4-a716-446655440000",
  clientName: "Client Y",
  contractValue: 75000,
  status: "active" as const,
  startDate: "2024-06-01T00:00:00Z",
};

// Asynchronous validation with refinements

const AsyncContractSchema = ContractSchema.extend({
  clientName: z.string().refine(
    async (val) => {
      // Simulate database check for duplicate client
      await new Promise((resolve) => setTimeout(resolve, 100));
      return val !== "Client X"; // Fail if client already has active contract
    },
    { message: "Client already has an active contract" }
  ),
});

AsyncContractSchema.safeParseAsync(asyncContract)
  .then((result) => {
    if (!result.success) {
      console.error("✗ Async validation errors:", result.error.format());
    } else {
      console.log("✓ Valid contract (async):", result.data);
    }
  })
  .catch((err) => console.error("Unexpected error:", err));

from pydantic import BaseModel, Field, ValidationError
from typing import Literal, Optional
from datetime import datetime
import asyncio


class Contract(BaseModel):
    contract_id: str
    client_name: str = Field(min_length=1)
    contract_value: float = Field(ge=0)
    status: Literal["active", "completed", "terminated"]
    start_date: datetime
    end_date: Optional[datetime] = None


async def check_no_duplicate_client(client_name: str) -> bool:
    """Simulate a database check for duplicate clients."""
    await asyncio.sleep(0.1)
    return client_name != "Client X"  # Fail if client already has active contract


async def validate_contract_async(data: dict) -> Contract:
    # Step 1: structural validation (Pydantic validators are synchronous)
    contract = Contract.model_validate(data)

    # Step 2: async business logic checks after structural validation passes
    if not await check_no_duplicate_client(contract.client_name):
        raise ValueError("Client already has an active contract")

    return contract


async def main():
    async_contract = {
        "contract_id": "660e8400",
        "client_name": "Client Y",
        "contract_value": 75000,
        "status": "active",
        "start_date": "2024-06-01T00:00:00Z",
    }

    try:
        contract = await validate_contract_async(async_contract)
        print("✓ Valid contract (async):", contract)
    except (ValidationError, ValueError) as e:
        print("✗ Validation error:", e)


asyncio.run(main())

Pydantic validators run synchronously. For async checks (like database lookups), validate the data structure first with model_validate(), then run async logic afterward—as shown above.

Comparison: TypeScript vs Python

Pattern	TypeScript (Zod)	Python (Pydantic)
Safe validation (no throw)	`safeParse()` → `{ success, data, error }`	`try/except ValidationError`
Strict validation (throws)	`parse()` → throws `ZodError`	`model_validate()` → raises `ValidationError`
Async validation	`.safeParseAsync()` / `.refine(async fn)`	Validate sync first, then run async checks
Skip validation	N/A	`model_construct()`
Access errors	`error.format()` / `error.issues`	`e.errors()` → list of dicts

Common pitfalls

Date parsing — Pydantic automatically parses ISO 8601 strings into datetime objects. Watch out for timezone-aware vs. naive datetimes: "2024-01-01T00:00:00Z" becomes timezone-aware, while "2024-01-01T00:00:00" is naive. Mixing them raises an error. Optional fields — Mark optional fields with Optional[X] = None (or X | None = None in Python 3.10+). A field typed as Optional[X] without a default is still required on input. Custom validators — Use @field_validator for single-field checks and @model_validator(mode='after') for cross-field checks:

from pydantic import BaseModel, field_validator, model_validator


class Contract(BaseModel):
    client_name: str
    start_date: datetime
    end_date: Optional[datetime] = None

    @field_validator("client_name")
    @classmethod
    def name_must_not_be_blank(cls, v: str) -> str:
        if not v.strip():
            raise ValueError("Client name cannot be blank")
        return v.strip()

    @model_validator(mode="after")
    def end_after_start(self) -> "Contract":
        if self.end_date and self.end_date <= self.start_date:
            raise ValueError("end_date must be after start_date")
        return self

TypeScript SDK

Learn about the Intuned Browser SDK for TypeScript.

Python SDK

Learn about the Intuned Browser SDK for Python.

Getting started

Intuned Agent

Web Tasks

Platform features

Learn

How-To

Integrations

References

Resources

Validate data with schemas

Recipe

Code example

Synchronous validation

Asynchronous validation

Comparison: TypeScript vs Python

Common pitfalls

TypeScript SDK

Python SDK

​Recipe

​Code example

​Synchronous validation

​Asynchronous validation

​Comparison: TypeScript vs Python

​Common pitfalls

​Related

TypeScript SDK

Python SDK

Recipe

Code example

Synchronous validation

Asynchronous validation

Comparison: TypeScript vs Python

Common pitfalls

Related