How to Convert JSON to TypeScript Types (Without Writing Them by Hand)

#webdev #javascript #beginners #tutorial

You just got access to a new API. The response comes back — it's a deeply nested JSON object with 40 fields, some optional, some arrays, some nested objects three levels deep. Your team lead says: "We need this typed properly." So you open a new .ts file and start typing interface...

That's an hour of your life you're not getting back — and the types might still be wrong.

Manual JSON-to-TypeScript conversion is one of those tasks that feels like real work but is basically just copying data shapes from one format to another. Here's a better way.

The Problem With Manual Type Writing

Hand-typing TypeScript interfaces from JSON has three common failure modes:

Missing optional fields — APIs often return null or omit fields in edge cases. If you type from a single example response, you'll likely mark optional fields as required.
Wrong primitive types — A field that looks like a number ("count": 42) might occasionally come back as a string ("count": "42") from a legacy backend. You won't catch this until runtime.
It doesn't scale — When the API response changes, you have to re-read and re-type the whole thing manually.

Real Example: Before and After

Say you get this from an API:

{
  "user": {
    "id": 1024,
    "name": "Alice",
    "email": "alice@example.com",
    "roles": ["admin", "editor"],
    "profile": {
      "bio": "Engineer at Acme",
      "avatar_url": "https://example.com/alice.png",
      "joined_at": "2024-01-15T09:30:00Z"
    },
    "settings": {
      "notifications_enabled": true,
      "theme": "dark"
    }
  }
}

If you wrote this by hand, you'd probably produce something like this:

interface Profile {
  bio: string;
  avatar_url: string;
  joined_at: string;
}

interface Settings {
  notifications_enabled: boolean;
  theme: string;
}

interface User {
  id: number;
  name: string;
  email: string;
  roles: string[];
  profile: Profile;
  settings: Settings;
}

interface ApiResponse {
  user: User;
}

That works — but you typed it from one example. Real-world responses can have bio: null, or avatar_url might be absent entirely. You'd discover those gaps at runtime, not at compile time.

Using the JSON to TypeScript converter, you paste the JSON and get properly structured interfaces in seconds. It handles nested objects, arrays, and can mark fields as optional — which is a much safer default for API responses.

Going Further: Runtime Validation With Zod

TypeScript types are compile-time only. They don't protect you at runtime — and if you're fetching from an external API, that's exactly when things go wrong.

A common pattern is pairing your TypeScript interfaces with a Zod schema so you can validate actual API responses at runtime:

import { z } from "zod";

const ProfileSchema = z.object({
  bio: z.string().nullable(),
  avatar_url: z.string().optional(),
  joined_at: z.string(),
});

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string(),
  roles: z.array(z.string()),
  profile: ProfileSchema,
  settings: z.object({
    notifications_enabled: z.boolean(),
    theme: z.string(),
  }),
});

// Runtime check — throws if the shape doesn't match
const response = await fetch("/api/user/1024");
const data = UserSchema.parse(await response.json());
// Now `data` is fully typed AND validated

You can generate this Zod schema automatically from any JSON using the JSON to Zod tool. The jsonindenter.com blog also has a deeper post on building Zod schemas from JSON for TypeScript projects that covers validation edge cases worth reading.

One More Step: Validate Before You Convert

If the JSON you're working with is malformed — missing quotes, trailing commas, comments copied from a config file — the converter will fail silently or produce wrong output. Run your JSON through a JSON validator first. It highlights the exact line with the problem so you fix it before conversion.

The full workflow looks like this:

Paste the raw JSON from the API response or config file
Validate it to catch any syntax issues
Convert to TypeScript interfaces (and optionally a Zod schema)
Drop the generated types into your codebase

This is especially useful when onboarding a new third-party API or when a backend teammate sends you a sample payload in Slack and you need types in under 60 seconds.

What Auto-Generation Can't Do (Yet)

Generated types have a ceiling. The tools give you the shape of your data, but they can't infer:

Semantic constraints — a status field might only accept "active" | "inactive" but the converter will type it as string
Cross-field relationships — if is_verified being true implies verified_at is non-null, you'll need to express that manually with a discriminated union
Generic patterns — paginated responses where the same wrapper type repeats across endpoints

For those cases, treat auto-generated types as a starting point, not a final answer. But for the vast majority of everyday API work, generation gets you 80% of the way there in seconds rather than spending 30 minutes typing interfaces that might still contain mistakes.

What's the most tedious JSON-to-types conversion you've done by hand? Did anything break when the API response changed later? Drop it in the comments — I'd genuinely like to know how others handle this.

Free tools used in this post: