Spec 29 — Pluggable Validation via Standard Schema

Purpose & motivation

Zod plays two roles in patties. Only one of them should be the user's concern.

Scope & non-goals

API surface change

One type changes in src/ai/types.ts. The generic TInput is now inferred from the Standard Schema's output type rather than Zod's.

import type { z } from "zod"

export interface ToolConfig<
  TInput = unknown,
  TOutput = unknown,
> {
  name: string
  description: string
  input: z.ZodType<TInput>
  handler: (
    input: TInput,
    ctx: AiContext,
  ) => Promise<TOutput> | TOutput
}

import type { StandardSchemaV1 } from "@standard-schema/spec"

export interface ToolConfig<
  TSchema extends StandardSchemaV1 = StandardSchemaV1,
  TOutput = unknown,
> {
  name: string
  description: string
  input: TSchema
  // optional escape hatch — see §4
  parameters?: JsonSchema
  handler: (
    input: StandardSchemaV1.InferOutput<TSchema>,
    ctx: AiContext,
  ) => Promise<TOutput> | TOutput
}

The JSON-Schema problem

This is the real engineering crux. Standard Schema defines runtime validation only — it carries no JSON-Schema export. But patties needs JSON Schema in two places: the Anthropic tool input_schema (wire format) and the agents-md CLAUDE.md manifest.

flowchart TB
    T["defineTool({ input })"]
    V["~standard.validate (runtime)"]
    R{"JSON Schema needed"}
    P["tool.parameters provided?"]
    Z["vendor === 'zod'"]
    O["other vendor"]
    JS["JSON Schema"]
    T --> V
    T --> R
    R --> P
    P -->|yes| JS
    P -->|no| Z
    Z -->|"dynamic import('zod') → z.toJSONSchema"| JS
    P -->|no| O
    O -->|"no converter → build error"| ERR["Actionable error:\nadd parameters: {...}"]
    classDef warn fill:#fef3c7,stroke:#d97706,color:#7c2d12;
    class ERR warn;
      

Resolution order

• 1 · ExplicitIf tool.parameters is set, use it verbatim. Always wins — the escape hatch for any validator.
• 2 · Vendor converterElse read input['~standard'].vendor. If a converter is registered (Zod ships by default via dynamic import("zod").toJSONSchema), use it.
• 3 · Fail loudElse throw a build-time error naming the tool and the fix: "Tool 'x' uses validator '<vendor>' which patties can't auto-convert to JSON Schema. Add a parameters JSON Schema to the tool." Never silently fall back to { type: "object" } — that would ship a broken tool definition to the model.

Runtime validation

In src/ai/run.ts, the per-tool-call safeParse becomes a Standard Schema validate. The spec allows validate to be async, so the call site awaits.

const parsed =
  tool.config.input.safeParse(use.input)
if (!parsed.success) {
  throw new ToolInputInvalid(
    use.name,
    parsed.error.issues,
  )
}
const out = await tool.config.handler(
  parsed.data, ctx,
)

const result = await tool.config
  .input["~standard"].validate(use.input)
if (result.issues) {
  throw new ToolInputInvalid(
    use.name,
    result.issues,
  )
}
const out = await tool.config.handler(
  result.value, ctx,
)

Error shape

ToolInputInvalid currently stores z.ZodIssue[]. It becomes vendor-neutral.

import type { StandardSchemaV1 } from "@standard-schema/spec"

export class ToolInputInvalid extends Error {
  readonly issues: ReadonlyArray<StandardSchemaV1.Issue>
  readonly tool: string
  constructor(tool: string, issues: ReadonlyArray<StandardSchemaV1.Issue>) {
    super(`Tool "${tool}" received invalid input: ${issues.length} issue(s).`)
    this.name = "ToolInputInvalid"
    this.tool = tool
    this.issues = issues
  }
}

A StandardSchemaV1.Issue is { message: string; path?: ReadonlyArray<PropertyKey | { key }> } — a strict subset of what ZodIssue carried, so anything formatting these issues for a response keeps working with a narrower read.

Validator examples

Same defineTool, three validators. Zod needs nothing extra; the others supply parameters until a converter is registered for them.

import { z } from "zod"
import { defineTool } from "patties/ai"

export default defineTool({
  name: "search",
  description: "Search hotel inventory.",
  input: z.object({
    city: z.string(),
    from: z.string(),
    to: z.string(),
  }),
  handler(input) {
    // input: { city, from, to }
  },
})

import * as v from "valibot"
import { defineTool } from "patties/ai"

export default defineTool({
  name: "search",
  description: "Search hotel inventory.",
  input: v.object({
    city: v.string(),
    from: v.string(),
    to: v.string(),
  }),
  parameters: {
    type: "object",
    properties: {
      city: { type: "string" },
      from: { type: "string" },
      to:   { type: "string" },
    },
    required: ["city", "from", "to"],
  },
  handler(input) { /* fully typed */ },
})

Dependency change

Backward compatibility

• Zod 4 is Standard-Schema-compliant. Every existing z.object() tool input satisfies StandardSchemaV1 with no edit — existing apps compile and run unchanged.
• The fixture app is the regression oracle. tests/fixtures/ai-app/app/tools/search.ts keeps its Zod schema; the generated CLAUDE.md tool JSON Schema must be byte-identical after the change.
• No API rename. defineTool, ToolConfig, and ToolInputInvalid keep their names and import paths; only types widen.
• This is additive → a minor release. No deprecation, no codemod.

Touch points

Acceptance criteria

• A tool defined with a Zod 4 schema works with no source change, and its generated JSON Schema is byte-identical to today's output.
• A tool defined with a Valibot or ArkType schema validates inputs correctly at runtime via ~standard.validate.
• A non-Zod tool with no parameters fails the build with an actionable error naming the tool and the fix — never ships { type: "object" }.
• A non-Zod tool with parameters emits that JSON Schema verbatim on the Anthropic wire and in CLAUDE.md.
• Invalid tool input throws ToolInputInvalid carrying StandardSchemaV1.Issue[]; the response surfaces the messages.
• @standard-schema/spec is the only new dependency; zod is still only reached by dynamic import() for non-AI users.
• bun run validate passes; the ai-app fixture and agents-md drift checks are green.