Why LLMs need schemas, not raw JSON

If you've ever pasted a JSON API response into an LLM prompt, you've probably noticed two things: the response is slow, and the model sometimes misreads the structure. Both problems have the same root cause. You're feeding it too much irrelevant data.

The token problem

LLMs process text as tokens. A typical JSON response from a REST API might be 800 tokens. Most of those tokens are values (strings, numbers, IDs) that the model doesn't need to understand the shape of the data. What it actually needs is the structure: field names, types, which fields are optional, and how things nest.

A schema strips out the values and keeps only the structure. The same 800-token payload becomes 120 tokens as a schema. That's an 85% reduction, which directly translates to faster responses and lower costs.

What goes wrong with raw JSON

When you hand a model raw JSON, it has to infer the structure itself. That works fine for small payloads, but it breaks down with larger ones:

• Repeated array items make the model read the same shape dozens of times
• Null values are ambiguous: is the field always null, or is it optional?
• Mixed-type arrays get misinterpreted when the model only sees a few items
• Deeply nested objects get lost in the noise of surrounding values

A schema solves all of these. Arrays are represented once with their item type. Nullable fields are explicitly marked. Union types are spelled out.

Schema vs TypeScript interfaces

There are two main ways to represent structure: a compact schema format and full TypeScript interfaces.

TypeScript interfaces are familiar to most developers, but they're verbose. Every field needs a type annotation, interfaces need names, and arrays need explicit bracket syntax. For LLM prompts, this verbosity is wasted tokens.

A simplified schema format is more compact:

{
  users: [{
    id: number
    name: string
    email: string | null
    role: string
    verified: boolean
    address: {
      city: string
      zip: string
    }
    nickname?: string
  }]
}

This is roughly 40% smaller than the equivalent TypeScript interfaces, while being just as readable for both humans and models.

When to use which

Use TypeScript interfaces when you're generating code, building SDKs, or need something that plugs directly into a TypeScript codebase.

Use a schema when you're writing LLM prompts, documenting APIs for human readers, or need to fit structure descriptions into tight context windows.

Both start from the same JSON input. The choice is about what you'll do with the output.

---

Try it yourself. Paste any JSON into the converter and switch between Schema and TypeScript modes to see the difference.