TypeScript Type vs Interface — Which to Use for JSON-Generated Shapes

Ask five TypeScript developers "type or interface?" and you'll get three opinions. For pure object shapes generated from JSON, the real differences are narrower than the debate suggests — but they matter in specific cases.

Here's the short answer: use interface for object shapes by default. Switch to type when you need union types, tuples, or mapped transformations. The reasoning matters because JSON-generated shapes often evolve into richer types, and picking the wrong one means rewriting later.

Short Answer for JSON-Generated Types

For the plain object shapes that come out of a JSON generator, interface and type compile to essentially the same thing. Both give you compile-time shape checking, autocomplete, and rename support.

Our generator produces interface output because that's the dominant convention in the TypeScript ecosystem — official docs, major libraries, and style guides lean that way. If you prefer type, swap the keyword; the field list stays identical:

interface User { id: number; email: string; }
// becomes
type User = { id: number; email: string; };

Practically equivalent. The differences show up when your types grow beyond plain objects.

Where They Actually Differ

The real divergences between interface and type:

Feature	interface	type
Plain object shape	Yes	Yes
Union types (A | B)	No	Yes
Tuple types	No	Yes
Mapped types	No	Yes
Conditional types	No	Yes
Primitive alias (type Id = number)	No	Yes
Declaration merging	Yes	No
extends syntax	Yes	& intersection instead
implements on a class	Yes	Yes (limitations)

Two of these matter most often: union types (type alias only) and declaration merging (interface only).

Sell Custom Apparel — We Handle Printing & Free Shipping

When Union Types Force You Toward type Alias

API responses that vary by discriminator are a common case. The shape depends on a type field:

type ActivityItem =
  | { kind: "comment"; text: string; postId: number }
  | { kind: "like"; postId: number }
  | { kind: "follow"; targetUserId: number };

You cannot express this with interface directly. Interfaces describe one shape; unions describe "one of several shapes." If your JSON contains variant records, type alias is the right tool.

Our generator produces an interface for each variant you paste, but it won't infer the union automatically — it only sees the shape of the element you gave it. After generating each variant interface, you combine them by hand:

type ActivityItem = CommentItem | LikeItem | FollowItem;

Short step, but worth knowing when you'll need to take it.

When Declaration Merging Earns Interface Its Keep

Interfaces can be declared twice in the same scope, and TypeScript merges them. Type aliases cannot:

interface User { id: number; }
interface User { email: string; }
// Merged: interface User { id: number; email: string; }

This sounds like a footgun and it can be. The main reason it exists is to let libraries extend third-party types without forking them. If you've ever added a property to Express's Request object via declare global { namespace Express { interface Request { user: User; } } }, that's declaration merging.

For JSON-generated application types, declaration merging rarely comes up. But if your project integrates with a library that expects you to augment its interfaces, interface is the required path.

What Most TypeScript Codebases Actually Do

After years of the "type vs interface" debate, the practical conventions most codebases settle on:

• Object shapes: interface. API response types, DTOs, form shapes, props interfaces.
• Unions, tuples, mapped types: type. Discriminated unions, utility types, anything that isn't a plain object.
• Primitive aliases: type. type UserId = number. Interface can't do this.
• Library augmentation: interface. Declaration merging, module augmentation.

Consistency inside a codebase matters more than picking "the right one" — a team that uses type for everything is fine, a team that uses interface for everything (where possible) is fine. Mixing the two requires a rule, and the rule above is the one most TypeScript teams converge on.

For JSON-generated shapes, our generator sticks with interface. It matches the dominant convention and leaves room for future augmentation if you need it.

Frequently Asked Questions

Is there a performance difference between type and interface?

No meaningful runtime difference — both compile away. Compile-time performance on very large codebases can favor interface in some edge cases, but in practice you will not notice.

Can I switch from interface to type later without breaking code?

Usually yes, for plain object shapes. Consumers using the type do not care which keyword defined it. Watch for declaration merging (interface-only) and extends syntax.

Why does the generator output interface instead of type?

Interface is the dominant convention for object shapes in TypeScript. If you prefer type, swap the keyword — the field list is identical.

Should I use type or interface for React component props?

Either works. Most React codebases use interface for props by convention, but type is fine and some teams prefer it for consistency with their union-heavy state types.