Home → JSON to TypeScript Guide

JSON to TypeScript: Complete Guide with Examples (2026)

Converting JSON to TypeScript interfaces is one of the most common tasks when building typed APIs. Instead of manually writing interfaces, you can generate them automatically — saving time and eliminating typos. This guide covers everything: type mapping, nested objects, optional fields, arrays, generics, and best practices.

What Is a TypeScript Interface?

A TypeScript interface defines the shape of an object — what properties it has and what types those properties are. When you fetch JSON from an API, TypeScript has no idea what shape the response has. By creating an interface that matches your JSON structure, you get:

• Type safety — TypeScript warns you at compile time if you access a property that doesn't exist
• Autocomplete — Your IDE knows every field and its type as you type
• Refactoring — Rename a property and TypeScript finds every usage instantly
• Documentation — Interfaces serve as living docs for your API response shapes

JSON to TypeScript Type Mapping

Every JSON value maps to a specific TypeScript type:

JSON Value	JSON Type	TypeScript Type	Example
"hello"	string	string	name: string
42	number	number	age: number
3.14	number	number	score: number
true	boolean	boolean	isActive: boolean
null	null	null	data: null
["a","b"]	array	string[]	tags: string[]
[1, 2, 3]	array	number[]	ids: number[]
{...}	object	interface	address: Address
[1, "a"]	mixed array	(number | string)[]	mixed: (number | string)[]

Basic Example: Simple JSON to Interface

Start with a simple flat JSON object:

{
  "id": 1,
  "name": "Alice",
  "email": "alice@example.com",
  "age": 28,
  "isActive": true,
  "score": 9.5,
  "bio": null
}

The generated TypeScript interface:

interface User {
  id: number;
  name: string;
  email: string;
  age: number;
  isActive: boolean;
  score: number;
  bio: null;
}

Nested Objects

When JSON has nested objects, the generator creates separate interfaces for each nested structure and references them:

{
  "user": {
    "id": 1,
    "name": "Alice",
    "address": {
      "street": "123 Main St",
      "city": "New York",
      "zip": "10001"
    }
  }
}

Generated TypeScript:

interface Address {
  street: string;
  city: string;
  zip: string;
}

interface User {
  id: number;
  name: string;
  address: Address;
}

interface RootObject {
  user: User;
}

Each nested object becomes its own named interface, making the code clean and reusable. The outer interface references the inner one by name.

Arrays of Objects

Arrays of objects are very common in API responses. Here's how they convert:

{
  "users": [
    { "id": 1, "name": "Alice", "role": "admin" },
    { "id": 2, "name": "Bob", "role": "user" }
  ],
  "total": 2
}

Generated TypeScript (the first array element is used to infer the item type):

interface UsersItem {
  id: number;
  name: string;
  role: string;
}

interface RootObject {
  users: UsersItem[];
  total: number;
}

Optional Fields

JSON APIs often return fields that may or may not be present. Mark these with ? in TypeScript:

interface User {
  id: number;
  name: string;
  email?: string;          // may not be present
  avatar?: string | null;  // present but possibly null
  metadata?: Record<string, unknown>;
}

The automated converter generates non-optional fields by default. After generating, review and add ? to any fields your API might omit.

Handling null Values Properly

There's an important distinction between null and undefined in TypeScript:

• field: null — always null, never changes
• field: string | null — can be a string or null (nullable)
• field?: string — may not exist on the object (optional)
• field?: string | null — optional AND nullable

When your JSON shows null for a field, the real-world type is usually string | null or number | null. The generator uses null as a conservative choice — update it to match your actual API contract.

Real-World API Example

Here's a realistic GitHub API user response converted to TypeScript:

{
  "login": "octocat",
  "id": 1,
  "avatar_url": "https://github.com/images/error/octocat_happy.gif",
  "html_url": "https://github.com/octocat",
  "public_repos": 2,
  "public_gists": 1,
  "followers": 20,
  "following": 0,
  "created_at": "2008-01-14T04:33:35Z",
  "updated_at": "2008-01-14T04:33:35Z"
}

interface GitHubUser {
  login: string;
  id: number;
  avatar_url: string;
  html_url: string;
  public_repos: number;
  public_gists: number;
  followers: number;
  following: number;
  created_at: string;   // ISO date string — consider using Date
  updated_at: string;
}

interface vs type: Which Should You Use?

Both interface and type can describe object shapes. Here's when to use each:

Use interface when…	Use type when…
You want to extend it with extends	You need union types: A | B
You want to implement it in a class	You need intersection types: A & B
Describing plain API response objects	You need mapped/conditional types
Declaration merging is needed	Tuple types or primitive aliases

For JSON API responses, interface is the conventional choice. Either works.

Using Your Interface with fetch()

Once you have the interface, use it to type your API calls:

interface User {
  id: number;
  name: string;
  email: string;
}

async function getUser(id: number): Promise<User> {
  const response = await fetch(`/api/users/${id}`);
  if (!response.ok) throw new Error('Failed to fetch user');
  const data: User = await response.json();
  return data;
}

// TypeScript now knows data.name, data.email, data.id
const user = await getUser(1);
console.log(user.name); // ✅ Type-safe

Advanced: Generic API Response Wrapper

Many APIs wrap responses in a common envelope. Use generics to type it once:

interface ApiResponse<T> {
  data: T;
  status: number;
  message: string;
  pagination?: {
    page: number;
    total: number;
    perPage: number;
  };
}

// Usage:
type UserResponse = ApiResponse<User>;
type UserListResponse = ApiResponse<User[]>;

const response: UserResponse = await fetchUser(1);

TypeScript Utility Types for JSON Data

TypeScript's built-in utility types are extremely useful when working with JSON interfaces:

• Partial<User> — makes all fields optional (useful for PATCH requests)
• Required<User> — makes all fields required
• Readonly<User> — prevents mutation of the object
• Pick<User, 'id' | 'name'> — select only specific fields
• Omit<User, 'password'> — exclude sensitive fields
• Record<string, User> — dictionary/map of users

Best Practices

1. Generate, then review — Use the tool to generate the base interface, then manually refine nullable and optional fields
2. Keep interfaces close to their usage — Co-locate interface definitions with the files that use them
3. Use unknown over any — For truly dynamic fields, prefer unknown which forces you to narrow the type before use
4. Version your API types — When an API changes, create a new version of the interface rather than mutating the old one
5. Share types between frontend and backend — Put shared interfaces in a types/ package that both sides import

Frequently Asked Questions

Related Tools & Guides

JSON to Python  |  JSON to Go  |  JSON to Java  |  JSON to Rust  |  JSON Schema Tutorial  |  How to Validate JSON  |  JSONPath Tutorial