Claude Code for Standard Schema — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are using the Standard Schema specification to write validator-agnostic code that works with Zod, Valibot, ArkType, or any compliant validation library. Standard Schema defines a common interface so libraries, frameworks, and tools can accept any validator without coupling to a specific one. Claude Code can implement Standard Schema patterns, but it hardcodes Zod usage instead of using the agnostic interface.

What Claude Code Gets Wrong By Default

  1. Imports Zod directly in library code. Claude writes import { z } from 'zod' in shared libraries and framework code. Standard Schema lets you accept any validator by type-checking against the StandardSchema interface instead.

  2. Uses Zod-specific methods in generic utilities. Claude calls .parse(), .safeParse(), and .shape which are Zod-specific. Standard Schema defines ~standard.validate() as the universal validation method.

  3. Couples form libraries to a single validator. Claude configures form libraries with explicit Zod resolvers. Frameworks supporting Standard Schema accept any compliant validator directly without framework-specific adapters.

  4. Ignores the type inference protocol. Claude manually types output as z.infer<typeof schema>. Standard Schema provides InferOutput<typeof schema> that works across all compliant libraries.

The CLAUDE.md Configuration

# Standard Schema Project

## Validation
- Spec: Standard Schema (validator-agnostic interface)
- Validators: Zod, Valibot, or ArkType (all compliant)
- Interface: StandardSchema from @standard-schema/spec

## Standard Schema Rules
- Library/framework code uses StandardSchema interface, not Zod
- Validate with: schema['~standard'].validate(data)
- Type inference: InferOutput<typeof schema>
- Accept any validator: function process<T extends StandardSchema>(schema: T)
- Zod/Valibot/ArkType all implement StandardSchema
- User code picks the validator; library code stays agnostic
- Check result: if (result.issues) for errors

## Conventions
- Framework internals accept StandardSchema, not specific validators
- User-facing APIs accept StandardSchema type parameter
- Example usage shows Zod, Valibot, AND ArkType options
- Type exports use StandardSchema inference, not library-specific
- Test with multiple validators to verify agnostic behavior
- Documentation shows all three validator options

Workflow Example

You want to create a form handler that accepts any Standard Schema validator. Prompt Claude Code:

“Create a generic createForm function that accepts a Standard Schema validator for form validation. It should work with Zod, Valibot, or ArkType schemas passed by the user. Include type inference for the form data.”

Claude Code should define createForm<T extends StandardSchema>(schema: T) that uses schema['~standard'].validate(data) for validation, infers the form data type with InferOutput<T>, checks result.issues for validation errors, and does not import any specific validation library.

Common Pitfalls

  1. Using ~standard wrong in type checks. Claude accesses schema['~standard'] at the type level instead of the value level. The ~standard property is a runtime value with validate() — use it for validation calls, not type narrowing.

  2. Version mismatches between spec and validators. Claude installs @standard-schema/spec but uses an older version of Zod that does not implement the interface yet. Standard Schema support was added in Zod 3.24+, Valibot 1.0+, and ArkType 2.0+.

  3. Over-abstracting user-facing code. Claude makes everything use StandardSchema even in application code where you have already chosen Zod. Standard Schema is for library authors — application code can and should use their chosen validator’s full API directly.