dileep kumar

Posted on Apr 1

Stop Writing Zod Schemas by Hand: What I Learned After 40 API Endpoints

#api #automation #productivity #typescript

I have a confession to make.

I spent three hours debugging a Zod schema on a Friday night. Not because the validation was complex. Not because the business logic was tricky.

Because the backend team renamed avatar to avatar_url in a deeply nested object. And I missed it.

Three hours. For a single field name change.

If you work with TypeScript and APIs, you know the drill. You have:

Your TypeScript types
Your Zod schemas for runtime validation
The actual JSON data from your API

Three versions of the same data shape. All have to stay in sync.

And when something changes, you get to play detective. Scrolling through JSON responses, comparing field names, updating schemas, hoping you didn't miss anything.

The Breaking Point

I was maintaining a project with around 40 API endpoints. Each one returning nested objects, arrays, optional fields, nullable values.

Every time the backend team deployed, I'd open my editor and do the same dance:

Copy the new JSON response
Compare it to my existing schema
Update field by field
Test
Fix the typos I inevitably made
Test again

I made the same mistakes over and over:

❌ Forgetting to mark a field as optional

❌ Missing that an ID changed from string to number

❌ Not handling null values properly

❌ Typing avatar instead of avatar_url

The bugs would show up in production. Users would get validation errors for fields that existed. Forms would fail because of fields that were actually optional.

I was spending more time fixing schema bugs than building features.

The Idea

I started wondering: Why am I writing these manually?

The JSON response is right there. The schema is just a structured version of that same data. Couldn't something automate this?

So I built a tool that does exactly that.

How it works:

You paste a JSON response. The tool looks at the actual data and figures out:

What type is each field? (string, number, boolean, array, object)
Are there any special patterns? (emails, URLs, UUIDs, dates)
Which fields are always present vs sometimes missing?
Which values can be null vs always have data?

Then it generates a Zod schema.

Not a perfect schema. But a correct, working schema that you can use immediately.

What It Actually Saves You

Here's what a typical API response looks like in my project:

{
  "status": "success",
  "code": 200,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Something important",
        "createdAt": "2024-03-15T10:30:00Z",
        "metadata": {
          "views": 1234,
          "tags": ["featured", "popular"],
          "expires": null
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 150,
      "hasNext": true
    }
  }
}

Writing the schema for this manually would take me about 10 minutes. That's if I don't make any mistakes.
`

🧠 What It Caught Automatically

One of the coolest parts of using this tool was noticing the details it picked up without any effort:

UUID format for the id
ISO datetime format for createdAt
Nullable field for expires
Array of strings for tags

Would I have caught all that manually?

Maybe.

But I definitely would've spent time checking each field.

⚡ The Unexpected Benefit

The tool did something I didn't expect.

When the generated schema didn't match my expectations, I started investigating the data more carefully. And that’s when things got interesting…

👉 I found bugs I would've never noticed otherwise.

🐛 Real Example #1

One time, the schema showed a field that was always null.

So I dug into our API logs...

Turns out:

The backend had deprecated that field months ago
Nobody updated the documentation
I had been validating it incorrectly the whole time

🐛 Real Example #2

Another time, I noticed the generated schema had optional fields that I had always treated as required.

After checking:

Some API responses were omitting those fields
My validation was silently failing for certain users

💡 The Realization

The tool wasn't just saving me time.

👉 It was making my code more accurate.

📚 What I Learned

Zod is powerful, but writing schemas manually is still tedious
The real value is in validation, not typing everything by hand
Automating repetitive work isn’t lazy — it’s efficient
API responses often have hidden patterns you don’t notice
A working generated schema > a perfect schema you never write

🚀 Try It Yourself

I put this tool online because if I needed it, chances are others do too.

👉 ToolsVIA JSON to Zod Converter

https://www.toolsvia.app/json-to-zod

✨ How It Works

Paste your JSON
Click convert
Done

No signup.

No data upload (everything runs in your browser).

No hidden costs.

🎯 Final Thought

If you're tired of playing detective with your API responses, give it a try with one of your real endpoints.

It won’t solve all your problems…

👉 But it might save you a Friday night or two 😄

💬 Your Turn

What’s your most memorable debugging story?

Ever spent hours on something that should have been simple?

Drop it in the comments — I’d love to know I’m not the only one 👇

DEV Community