TypeScript Interface or Zod Schema from Excel? When to Use Each

Untrusted upload -> Zod, not interface

A customer uploads an order sheet. An interface would compile but let a string slip into qty at runtime; Zod rejects it.

Sample: { orderId: "X1", qty: 3 }

Interface (compile-time only, NO runtime guard):
interface OrderRow { orderId: string; qty: number }

Zod (runtime guard — ship this for uploads):
export const orderRow = z.object({
  orderId: z.string(),
  qty: z.number().int()
});
orderRow.safeParse({ orderId: "X1", qty: "oops" }) -> success:false

Derive the type — don't hand-maintain both

Generate Zod, then get the interface-equivalent for free. They can never drift apart.

export const orderRow = z.object({
  orderId: z.string(),
  qty: z.number().int()
});

// instead of a separate interface:
export type OrderRow = z.infer<typeof orderRow>;
// OrderRow === { orderId: string; qty: number }

Trusted internal config -> interface is enough

For a build-time config object you control, the interface gives types with zero runtime overhead.

Sample: { featureFlag: "beta", maxSeats: 50 }

Generate at /tool/json-to-typescript:
interface AppConfig {
  featureFlag: string;
  maxSeats: number;
}
// no Zod needed — you author this config, it is trusted

Strict template enforcement (Zod only)

An interface cannot reject an unexpected column; z.strictObject() can.

strictObjects: true ->
export const orderRow = z.strictObject({
  orderId: z.string(),
  qty: z.number().int()
});

orderRow.safeParse({ orderId: "X1", qty: 3, legacyCol: "x" })
-> success:false, 'Unrecognized key: legacyCol'
No interface can do this.

Both artifacts from Excel in one pass

When you genuinely want a standalone interface AND a Zod schema from the sheet, use the Excel-native tRPC Router Builder.

/excel-tools/excel-trpc-router on an Orders sheet emits:

export const OrdersSchema = z.object({
  orderId: z.string().optional(),
  qty: z.number().optional()
});
export interface Orders {
  orderId?: string;
  qty?: number;
}
// plus list/getById/create/update/delete procedures

TypeScript interfaces are erased at compilation — they cannot catch a missing column or wrong type in an actual uploaded file. For any untrusted Excel input, use Zod's safeParse.

Two definitions for one shape drift apart over time. Generate the Zod schema and derive the type with z.infer<typeof schema> so there is a single source of truth.

Both Excel-to-TypeScript and Excel-to-Zod redirect to JSON-sample tools that take .json/.ndjson/.jsonl/.txt. Convert the sheet to JSON first, or use the tRPC Router Builder for direct .xlsx.

The JSON to Zod generator never adds .optional() — it reads one sample value. The Excel-native tRPC Router Builder does wrap every field in .optional() because it samples rows; the JSON-to-TypeScript generator likewise infers from one sample.

Neither generator detects dates: the interface gets string, the Zod schema z.string(). Refine the Zod side with .date()/.coerce.date(); the interface stays string since it never validates.

z.strictObject() rejects extra columns, which an interface never does. If you want interface-like permissiveness with runtime checks, use the default z.object() (strips extras) rather than strict mode.

Both generators JSON.parse the input; a malformed paste throws and produces nothing. Stringify a clean row with JSON.stringify(rows[0], null, 2).

Both are Pro tools with a 2 MB free cap. One representative row is all either generator needs — never paste the whole workbook.

Zod validation per row is microseconds; the cost is rarely measurable next to parsing the file or hitting the DB. The safety on an untrusted boundary far outweighs it. Use interfaces only where you have already validated.

sheet_to_json flattens to a single level, so both outputs are flat. If you need nested objects, nest the JSON manually before pasting; both generators recurse into nested JSON correctly.