DEV Community: JSON to TS

How to convert a JSON sample to a Valibot schema (and the 3 ways the algorithm diverges from Zod)

JSON to TS — Sun, 10 May 2026 08:41:37 +0000

When you sit down to build runtime validation for an API boundary in TypeScript, the first half-hour goes into picking a library. Zod is the default. Valibot is the 2026 upstart that you start hearing about once your bundle size gets audited — same expressive surface, but pipe-based composition and per-primitive tree-shaking instead of a monolithic chainable class.

Both libraries answer the same question: given an unknown JSON value at runtime, prove its shape. And both expect you to write the schema by hand. That's the part nobody likes. So I wrote a converter — paste a JSON sample, get back a Valibot schema you can tighten by hand. The tool is here, free, no signup, runs entirely in the browser: json-to-ts-app.netlify.app.

Internally the Valibot emitter is a sister function to the Zod emitter I wrote up last week. Same shape walk, same naming/uniquify logic, same children-first ordering. But three things have to change once you switch validators — and they're not the things you'd guess from skimming the Valibot README. This post is about those three.

The shape walk (recap)

The walk is unchanged. For each node in the JSON sample:

Primitive → emit the leaf schema (v.string(), v.number(), v.boolean(), v.null()).
Array → recurse on every element, dedupe the resulting schemas into a union if mixed, collapse to a bare schema if uniform.
Object → recurse on every value, give the object a const NameSchema = v.object({...}) binding, push it into the output list after its children so the const order is valid.
Optional → if a key is missing in any sibling sample (multi-sample input), mark its value optional.
Mixed types → wrap them in a union.

Children-first ordering still matters even though we're no longer in Zod-land: const bindings don't hoist in JavaScript, so const Root = v.object({ user: User }) requires User to already exist by the time that line runs. Same constraint, same fix.

What changes is how each node emits. Three divergences from Zod, all non-obvious:

1. `v.optional()` wraps the schema — it doesn't chain on it

In Zod, you write:

z.string().optional()

.optional() is a method on the Zod schema instance. It returns a new schema that mutates the inner one's behavior. That's why a long Zod field reads left-to-right, like a fluent builder: z.string().min(3).max(20).optional().

Valibot has no such method. It has a top-level function called optional that takes a schema and returns a new one:

v.optional(v.string())

So the emitter's per-key code path can't just append ".optional()" to whatever schemaStr it built. It has to wrap:

var wrapped = info.optional
  ? "v.optional(" + schemaStr + ")"
  : schemaStr;

This sounds like a one-line difference — and it is — but it forces a small rethink for anyone porting a Zod codebase by hand. You don't dot a method on at the end; you wrap from the outside. Multi-modifier fields (e.g. optional + nullable) compose as nested calls: v.optional(v.nullable(v.string())), not .string().nullable().optional(). The reading order flips inside-out.

The emitter never emits a multi-modifier field today (JSON samples don't tell you "this is nullable"; they only tell you "this is null sometimes" — which becomes a union with v.null()). But the wrap pattern is the right primitive for the moment that changes.

2. The header is a namespace import, not destructured

Zod's idiomatic header is destructured:

import { z } from "zod";

The emitter for the Zod path emits exactly that. For Valibot, the emitter switches to a namespace import:

import * as v from "valibot";

Why? Because Valibot's main pitch is per-primitive tree-shaking. Every combinator (v.string, v.object, v.optional, v.union) is a separate exported symbol that gets dead-code-eliminated by the bundler if you don't use it. A 5-field schema using only v.object and v.string should ship ~600 bytes of Valibot, not the 12KB you'd get from a destructured-everything import.

Bundlers can in theory tree-shake destructured imports too. In practice — and Valibot's docs are explicit about this — the namespace form is the path that lines up with the analyzer. Some bundlers (esbuild and Vite are reliable; older Webpack + Babel pipelines less so) drop dead namespace properties cleanly only when the namespace is the import shape.

The single-letter v. prefix keeps callsites tight either way: v.object({ id: v.string() }) reads about the same as z.object({ id: z.string() }). The cost is paid in the import line, the win is paid back at every byte of bundle.

3. `v.union([...])` is the only composition path — there is no `.or`

Zod gives you two ways to spell a sum type:

// chain form
z.string().or(z.number())

// function form
z.union([z.string(), z.number()])

Both work. The Zod emitter picks the function form because it reads better at arity > 2 and matches the docs.

Valibot only has the function form:

v.union([v.string(), v.number()])

There is no .or() method to chain. There is no .and() either — v.intersect([...]) is its analogue. The whole API is composition-by-function-call, never method-chaining. This is part of the same design that drove decision #1: a Valibot schema is a value, not an object with methods, so all combinators are top-level functions.

For the emitter that means there's only one branch to write. The mixed-type case collapses to:

if (union.length === 0) return "v.unknown()";
if (union.length === 1) return union[0];
return "v.union([" + union.join(", ") + "])";

(The v.unknown() for empty arrays is a deliberate echo of the Zod path: a literal v.never() would reject any element, which is wrong for a sample that just happened to be empty. v.unknown() matches the TS-side unknown[].)

The single-type-collapse is the same trick the Zod emitter uses — a 1-arg union like v.union([v.string()]) is degenerate and the bare schema reads identically. Worth dropping.

A real example: a Stripe webhook → Valibot

Paste a Stripe webhook payload into the Stripe webhook → Valibot landing page and you get something like this:

import * as v from "valibot";

const DataObjectSchema = v.object({
  id: v.string(),
  object: v.string(),
  amount: v.number(),
  currency: v.string(),
  status: v.string(),
  customer: v.optional(v.union([v.string(), v.null()])),
  metadata: v.object({}),
});

const DataSchema = v.object({
  object: DataObjectSchema,
});

const RootSchema = v.object({
  id: v.string(),
  object: v.string(),
  api_version: v.string(),
  created: v.number(),
  data: DataSchema,
  type: v.string(),
});

All three divergences show up in this output:

The header is import * as v (decision #2).
The optional-and-nullable customer field wraps from the outside: v.optional(v.union([v.string(), v.null()])) (decision #1 + decision #3 stacked).
Children come first: DataObjectSchema is declared before DataSchema, which is declared before RootSchema. Try to flip the order and the bundler / TS compiler complains about referencing a const before its declaration.

The same machinery handles an AWS Lambda event → Valibot conversion, a webhook from any other provider, or any pasted JSON sample. The output is meant to be a starting point — you'll usually tighten v.string() into v.pipe(v.string(), v.email()) for the email field, narrow v.string() to v.literal("payment_intent.succeeded") for known event types, and so on. But you don't write the 80-line v.object shell by hand.

Why convert to Valibot specifically

Two reasons people pick Valibot over Zod in 2026:

Bundle size. A medium-sized validation surface (say, 30 schemas across 8 endpoints) drops from ~14KB Zod-minified to ~2-3KB Valibot-minified, because every combinator you don't import gets dropped. For a public-facing landing page or a mobile-first app, that's the reason you switch.
Pipe-based refinement. Rather than chaining methods on a string schema, you compose with v.pipe(v.string(), v.email(), v.minLength(5)). The schema is built outside-in instead of inside-method-by-method. It reads more like a function pipeline, less like a builder DSL.

If neither of those applies — and you're already deep in a Zod codebase — staying on Zod is fine. The converter has both modes; flip the toggle at the top of the tool and the same JSON sample comes out as either schema family. The point of the converter isn't to take a side; it's to skip the boring part.

The three divergences in this post are the only places where the algorithm has to actually change. The other 90% of the work — naming, ordering, deduping, multi-sample merging — is the same shape walk in both modes. Which is, in retrospect, why a "second emitter" was a Friday-afternoon ship rather than a week-long project.

How to convert a JSON sample to a Zod schema (and the 4 algorithm choices behind a working converter)

JSON to TS — Sun, 10 May 2026 08:08:54 +0000

A Stripe signature header proves the bytes came from Stripe. It does not prove the bytes match the shape your handler expects. The same trap exists for every JSON crossing a runtime boundary: webhooks, queue payloads, third-party API responses, AI tool calls. TypeScript types are a compile-time annotation; the actual JSON drifts over time.

Zod closes that gap by validating shape at runtime. The friction is hand-writing the schema. So I built a small in-browser tool that does it for you — paste a JSON sample, get a runnable z.object. This post is about the four non-obvious algorithm choices that came out of that build.

The tool is here, free, no signup, pure client-side: json-to-ts-app.netlify.app (toggle the output mode to zod).

The shape walk

Conceptually a JSON → Zod converter is a tree walk: visit every node, emit a Zod expression. Primitives map to z.string() / z.number() / z.boolean() / z.null(). Objects become z.object({...}). Arrays become z.array(...). Easy.

The trouble starts the moment you want output that compiles, that's readable, and that doesn't surprise anyone six months from now. Here are the four spots where the obvious choice is wrong.

1. Children-first const ordering

TypeScript interfaces hoist:

interface Root { user: User }
interface User { id: string }   // declared after Root, still works

Zod schemas don't:

const RootSchema = z.object({ user: UserSchema });   //  UserSchema is undefined here
const UserSchema = z.object({ id: z.string() });

const doesn't hoist. So the emission order has to be children before parents. The TS-side walk reserves the parent's slot in the output array first, then recurses. The Zod-side walk has to do the opposite: recurse first, then push the parent's slot. Same algorithm, inverted slot ordering — easy to get wrong if you copy the TS path verbatim.

function generateZodObject(merged, hint) {
  // Allocate the name eagerly so the root claims its name first.
  const schemaName = uniquify(...) + "Schema";

  const lines = [];
  for (const key of Object.keys(merged)) {
    const childSchema = valuesToZod(merged[key].values, key); // recurse FIRST
    lines.push(`  ${quoteKey(key)}: ${childSchema}${merged[key].optional ? ".optional()" : ""},`);
  }

  // Push LATE — after children are pushed.
  schemas.push({ name: schemaName, body: `const ${schemaName} = z.object({\n${lines.join("\n")}\n});\n` });
  return schemaName;
}

2. Mixed-type arrays → `z.union`, not chained `.or()`

Both work. Both produce identical runtime behaviour. But z.union([z.string(), z.number(), z.null()]) reads better than z.string().or(z.number()).or(z.null()) once arity goes past two, and z.union is what the official Zod docs and the bulk of real codebases use. Generated code that looks like the docs is generated code people trust.

The single-element case collapses to the bare schema (no degenerate one-arg union). Empty arrays specifically become z.array(z.unknown()) — z.never() would be wrong, because it would reject every non-empty array later.

3. `.optional()`, not `.nullish()`

These are semantically different and people mix them up.

Operator	Allows missing key	Allows `null` value
`.optional()`	yes	no
`.nullable()`	no	yes
`.nullish()`	yes	yes

If you merge several samples of the same shape and the field is missing in some samples, that's optional. If the field is present-but-null in some samples, that's nullable. They are different signals and the converter keeps them separate: optional is set when an array of similar objects has the key missing on at least one item; null values surface as a z.null() member of the value's union.

4. Each non-leaf object becomes its own named const

The "easy" implementation inlines everything into one giant z.object. A Stripe webhook output looks like an 80-line nested expression nobody will diff or reuse. The converter instead names each non-leaf object — RootSchema, DataSchema, ObjectSchema, etc. — and uniquifies on collision (UserSchema, UserSchema2).

Same code that handles TypeScript interface naming, just with a Schema suffix appended.

A real example: Stripe webhook

Paste a payment_intent.succeeded event into json-to-ts-app.netlify.app/stripe-webhook-to-zod/ and you get four named schemas in dependency order: the inner data.object first, then DataSchema referring to it, then RootSchema referring to that. Drop the output into your handler:

import { z } from "zod";

const event = RootSchema.parse(JSON.parse(req.body));
//    ^? type-narrowed; missing/extra fields throw a single named error

Multiple event types? Generate one schema per type, then combine them with z.discriminatedUnion("type", [...]) and your handler narrows on event.type cleanly.

The same playbook works for any JSON-over-HTTP boundary — there are landing pages with worked examples for AWS Lambda events, GitHub API responses, OpenAI chat completions, and JSON:API documents under the same tool.

Why a converter at all?

Because hand-writing Zod schemas for nested API payloads is the most boring kind of code there is, and the time you spent writing it is time you didn't spend deciding what to do when validation fails. Generate it, edit it (rename the constants, tighten the types where you have stronger constraints than "string"), commit it.

The tool runs entirely in your browser — your JSON never leaves the tab. Source is MIT on GitHub if you want to see the full algorithm.

If you're on the fence about adding runtime validation: the cost is one parse call at the boundary, sub-millisecond on typical API payloads. The win is that schema drift becomes a single named error in one place, not a Cannot read property 'x' of undefined thirty stack frames deep.