✓ Last tested: May 2026 · Verified against TypeScript 5.4+

How to Convert JSON to TypeScript Interfaces (Free Tool + Manual Guide)

Field Notes: The 50-Field API Response Nightmare

Manually typing TypeScript interfaces from a 50-field API response takes 20 minutes. Here's how to do it in 3 seconds.

I remember my first week working on a large-scale e-commerce dashboard. The backend team handed me a Swagger document with a JSON response payload for the GET /api/v2/products/detailed endpoint. The JSON response was a behemoth—deeply nested arrays, mixed data types, polymorphic structures for variants, and over 50 distinct fields.

I spent nearly an hour manually mapping this JSON to TypeScript interfaces. The next day, the backend team changed three field names and added a nested metadata object. My build broke. I had to sift through the interface line by line to find the mismatch.

// The manual approach is brittle:
interface ProductResponse {
  id: string; // Wait, was this a number in the JSON?
  metadata: any; // I gave up here
  variants: Variant[];
  // ... 47 more lines
}

The breakthrough wasn't just finding an online converter; it was understanding how these converters parse raw JSON structures into Abstract Syntax Trees (AST) to generate type definitions perfectly. I learned that you should never manually type an API response. Always generate it. Let's break down exactly how to convert JSON to a TypeScript interface online, how the underlying rules work, and how to handle the inevitable edge cases.

---

What Is a TypeScript Interface and Why Generate It From JSON?

Quick Answer: A TypeScript interface defines the shape of an object, specifying the exact keys and data types allowed. Generating it from JSON guarantees that your frontend code perfectly mirrors your backend API response, eliminating runtime undefined errors caused by typos or mismatched types.

JSON (JavaScript Object Notation) is loosely typed. When you JSON.parse() a payload in TypeScript, the compiler assigns it the any type by default. This completely circumvenes TypeScript's type safety. By generating an interface, you lock down the data structure.

Interface vs Type Alias: When to Use What

When converting JSON, you usually have the choice between generating an interface or a type. Here is a reference matrix:

Feature	interface	type Alias
Declaration Merging	Yes. Multiple interfaces with the same name merge.	No. Types with the same name throw an error.
Object Shapes	Excellent. Preferred for defining object structures.	Good.
Unions & Primitives	No. Cannot define `string	number`.
Extensibility	Uses extends keyword.	Uses & (intersection).
Performance	Slightly better compiler performance for deep objects.	Can sometimes cause slow compilations if highly complex.

Rule of thumb: Generate an interface for standard JSON objects. Generate a type if the JSON contains mixed types or complex unions.

---

How to Convert JSON to TypeScript Interface Automatically

The easiest way to perform this translation is using an automated generator. If you need to convert JSON to TypeScript interface online, here is the exact workflow using standard converter tools:

Step 1 — Paste Your JSON Into the Converter

Obtain the raw JSON from your API response. Tools like Postman or your browser's Network tab are great for this. Copy the raw output and paste it directly into the converter's input pane. Ensure the JSON is valid; missing quotes or trailing commas will break the parser.

Step 2 — Choose Interface vs Type Alias

Look at the tool's configuration settings. If your JSON represents a standard API response model (e.g., a User or Post), select Interface. If your JSON root is an array of mixed elements, or if you prefer intersections over inheritance, select Type.

Step 3 — Handle Optional vs Required Fields

By default, JSON generators assume every field present in the JSON is required. If you know certain fields might be omitted by the backend, look for an "Optional" toggle, or manually add the ? modifier to the generated fields later.

Step 4 — Copy and Import Into Your Project

Copy the generated code and paste it into a dedicated .ts or .d.ts file in your project (e.g., types/api.ts).

// types/api.ts
export interface UserProfile {
  id: number;
  username: string;
  isActive: boolean;
}

---

Manual Conversion — How to Do It Yourself

Automated tools are fantastic, but understanding the manual translation process is critical when debugging edge cases or when dealing with highly dynamic JSON structures.

Simple Objects

A flat JSON object maps 1:1 to a TypeScript interface.

JSON:

{
  "name": "Alex",
  "age": 28,
  "isSubscribed": true
}

TypeScript:

interface Subscriber {
  name: string;
  age: number;
  isSubscribed: boolean;
}

Nested Objects (Interface Composition)

When JSON contains nested objects, you have two choices: inline the types or compose them. Composition (creating separate interfaces) is almost always better for reusability.

JSON:

{
  "orderId": "A123",
  "customer": {
    "name": "Jane",
    "email": "jane@example.com"
  }
}

TypeScript (Composed):

interface Customer {
  name: string;
  email: string;
}

interface Order {
  orderId: string;
  customer: Customer;
}

Arrays of Objects

For arrays, append [] to the type. If the array contains objects, create an interface for the singular object first.

JSON:

{
  "department": "Engineering",
  "employees": [
    { "id": 1, "role": "Dev" },
    { "id": 2, "role": "QA" }
  ]
}

TypeScript:

interface Employee {
  id: number;
  role: string;
}

interface Department {
  department: string;
  employees: Employee[];
}

Union Types From Mixed JSON

JSON arrays can hold mixed types. Interfaces cannot define direct unions, so you must use a type alias.

JSON:

{
  "values": [1, "two", false]
}

TypeScript:

interface MixedData {
  values: (number | string | boolean)[];
}

---

JSON to TypeScript Conversion Rules — Quick Reference

Keep this matrix handy when manually typing payloads or debugging generated code.

JSON Type	TypeScript Type	Example	Gotcha
string	string	"hello"	ISO dates are strictly string in JSON, not Date.
number	number	42 or 3.14	TypeScript does not distinguish between int and float.
boolean	boolean	true	Watch out for stringified booleans ("true").
array	T[] or Array<T>	[1, 2]	Mixed arrays become `(A
object	interface or Record	{"k":"v"}	Use Record<string, any> for dynamic keys.
null	null	null	Converters often guess any for null if the true type isn't present.

---

Common Conversion Errors and Fixes

After generating thousands of interfaces, I consistently see the same three errors crop up in codebases.

1. null Values Becoming "never" or "any" Type

If your JSON payload includes a null value, the converter has no way of knowing what type the field should be when it isn't null.

The Problem:

{ "discountCode": null }

Converts to:

interface Cart {
  discountCode: any; // or sometimes `never`
}

The Fix: Manually type the field based on your API schema. If it should be a string, update it to use a union:

interface Cart {
  discountCode: string | null;
}

2. Numeric Keys Breaking Interface Names

JSON allows numeric strings as keys, but TypeScript identifiers cannot start with a number.

The Problem:

{
  "2023": { "revenue": 1000 },
  "2024": { "revenue": 2000 }
}

The Fix: If the JSON represents a dictionary/hashmap, do not map each year as a specific property. Use an index signature instead:

interface RevenueData {
  [year: string]: {
    revenue: number;
  };
}

3. Date Strings Typed as string Not Date

JSON has no native Date type; dates are transmitted as ISO strings.

The Problem:

{ "createdAt": "2026-05-31T14:00:00Z" }

Converts to:

interface Post {
  createdAt: string; 
}

The Fix: You have two options. Leave it as a string if you are just passing it through. If you hydrate it into a Date object on the frontend, change the type:

interface Post {
  createdAt: Date;
}
// Note: You must manually execute `new Date(apiResponse.createdAt)`

---

JSON to TypeScript vs JSON Schema — What's the Difference?

A common point of confusion is the difference between a TypeScript Interface and a JSON Schema. They solve different problems.

Feature	TypeScript Interface	JSON Schema
Primary Purpose	Compile-time type checking.	Runtime validation and API contracts.
Environment	Development time (TypeScript).	Runtime environment (JS, Python, Go, etc).
Validation	Disappears after compilation. Cannot validate actual runtime payloads.	Can validate incoming data at runtime (e.g., using Ajv).
Metadata	Minimal (types, unions).	Extensive (min length, regex patterns, dependencies).

If you need to ensure the data coming from the server actually matches the shape you expect at runtime, use a library like Zod to parse the JSON and infer the TypeScript type automatically.

---

Frequently Asked Questions

Q: Can I convert JSON to a TypeScript class instead of interface? Yes, but standard converters generate interfaces or types since JSON lacks methods. To generate classes, you must parse the JSON and hydrate instances, or use libraries like class-transformer.

Q: How do I handle nullable fields in the generated interface? Ensure your strictNullChecks flag is enabled in tsconfig.json. When converting, nullable fields should be typed as T | null rather than relying purely on the optional ? modifier, as ? implies undefined, not null.

Q: What's the difference between interface and type in TypeScript? Interfaces are extendable via declaration merging and are generally preferred for object shapes. Types (type aliases) are better for unions, intersections, and primitives.

Q: Does the converter handle deeply nested JSON? Yes. Most modern converters recursively extract nested objects and generate separate interfaces or inline types for them, ensuring complete type safety across the entire payload tree.

---

Test your configurations and speed up your workflow directly in your browser. Use our free JSON to Code Generator to convert JSON to TypeScript, Go structs, and Pydantic models in seconds → JSON Code Generator

---

External Sources

• TypeScript Handbook: Interfaces
• MDN Web Docs: Working with JSON
• TypeScript Handbook: Everyday Types

---

Abu Sufyan · Full-stack developer · Founder of WebToolkit Pro Github

Last updated: May 2026