boundary-validation

Boundary Validation Skill

Iron Law

PARSE, DON'T VALIDATE

Use a function that accepts a less-structured input and produces a more-structured output — or fails. After parsing succeeds, the type system guarantees correctness; no downstream code ever rechecks. "The difference between validation and parsing is that parsing gives you a new value… whose type tells you the check has been performed." — Alexis King [1]

When This Skill Activates

• Creating API endpoints or routes
• Processing user-submitted data
• Integrating with external APIs
• Accepting environment variables or configuration
• Handling database queries with user input
• File uploads or webhook processing

Core Principle: Schema at Every Boundary

A boundary is any point where data crosses a trust domain [2][3]. External data is hostile until parsed through a schema [4]. After parsing, the type carries proof of validity — no redundant checks downstream [1].

// VIOLATION: Manual validation — checks scattered, no type proof [1]
function createUser(data: any): User {
  if (!data.email || typeof data.email !== 'string') throw new Error('Invalid');
  // ...scattered checks, easy to miss, no type guarantee
}

// CORRECT: Parse at boundary — schema yields typed value or error [5][6]
const UserSchema = z.object({
  email: z.string().email().max(255),
  age: z.number().int().min(0).max(150),
  name: z.string().min(1).max(100),
});

function createUser(data: unknown): Result<User, ValidationError> {
  const parsed = UserSchema.safeParse(data);
  if (!parsed.success) {
    return { ok: false, error: new ValidationError('Invalid', parsed.error) };
  }
  return { ok: true, value: parsed.data }; // typed User, guaranteed valid
}

Boundary Taxonomy

Boundary	Trust Level	Parse Strategy
HTTP request body/params/query	Zero trust	Schema + sanitize [4][7]
External API response	Low trust	Schema (API may change) [2]
Environment variables	Low trust	Schema on startup, fail fast [8]
File uploads	Zero trust	Schema + content sniffing + size limit [4]
Webhook payloads	Zero trust	Signature verify then schema parse [4][9]
Database reads	High trust	Schema optional (ORM types)
Internal function args	Full trust	Type system sufficient [1]