JSON to TypeScript Converter

Why Generate TypeScript Interfaces from JSON?

TypeScript’s type system is one of its greatest strengths, but writing interfaces manually for every API response, configuration file, or data model is tedious and error-prone. When you have a sample JSON payload — from an API response, a database export, or a mock file — automatically generating TypeScript interfaces saves time and ensures your types accurately reflect the actual data shape.

This is especially valuable during the early stages of integrating with a new API. You can copy a sample response from the API documentation, paste it into this tool, and get production-ready TypeScript interfaces in seconds. As the API evolves, you can regenerate interfaces from updated sample data.

How the Conversion Works

The converter analyzes the structure of your JSON data and generates corresponding TypeScript interfaces using these rules:

• Primitive values: JSON strings become string, numbers become number, booleans become boolean, and null becomes null.
• Objects: Each JSON object generates a named TypeScript interface. The interface name is derived from the property key in PascalCase. For example, a property "user_profile" generates an interface named UserProfile.
• Arrays: The converter inspects all elements to determine the array type. If all elements are the same type, it produces string[] or number[]. For arrays of objects, it merges all objects to find the complete set of keys and generates a single interface.
• Mixed arrays: If an array contains multiple types (e.g., strings and numbers), the converter produces a union type: (string | number)[].
• Nested structures: Nested objects are extracted into separate interfaces, with the parent referencing the child interface by name. This produces clean, readable output instead of deeply nested inline types.

Understanding TypeScript Interfaces

A TypeScript interface defines the shape of an object — what properties it has and what types those properties hold. Interfaces exist only at compile time; they produce zero runtime code and add zero bytes to your JavaScript bundle.

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

With this interface defined, TypeScript will catch errors at compile time: accessing a nonexistent property, passing the wrong type, or forgetting a required field. This catches bugs before your code ever runs.

Interface vs. Type Alias

TypeScript offers two ways to define object shapes: interface and type. For object types, they are largely interchangeable, but there are meaningful differences:

• Declaration merging: Interfaces with the same name are automatically merged. Types cannot be merged. This makes interfaces useful for extending library types.
• Extends vs. intersection: Interfaces use extends for inheritance; types use & intersection. Interface extension produces better error messages.
• Computed properties: Type aliases support mapped types, conditional types, and template literal types more naturally.
• Performance: The TypeScript compiler handles interfaces slightly faster than equivalent type aliases in large projects, because interfaces are cached by name.

This tool generates interfaces by default because they align with the TypeScript team’s recommendation for defining object shapes. For top-level arrays or primitives, it falls back to type aliases.

Optional Fields and Readonly Modifiers

Real-world data often includes fields that may or may not be present. TypeScript represents this with optional properties using the ? modifier:

interface User {
  id: number;
  name: string;
  nickname?: string; // may be undefined
}

This tool offers an option to mark all fields as optional, which is useful when working with partial data models, PATCH request bodies, or form state where not all fields are always present.

The readonly modifier prevents reassignment of properties after initialization:

interface Config {
  readonly apiUrl: string;
  readonly maxRetries: number;
}

Use readonly for configuration objects, API responses, and any data that should not be mutated after creation. This enforces immutability at the type level.

Working with Nested JSON

Most real-world JSON contains nested objects. Consider this API response:

{
  "user": {
    "id": 1,
    "name": "Alice",
    "address": {
      "city": "Portland",
      "state": "OR"
    }
  }
}

The converter generates three interfaces: Root, User, and Address. Each nested object becomes its own named interface, keeping the output flat and readable. The parent interfaces reference child interfaces by name:

export interface Root {
  user: User;
}

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

export interface Address {
  city: string;
  state: string;
}

Handling Arrays of Objects

When JSON contains an array of objects, the converter examines all elements to build a complete interface. If some objects have extra fields that others lack, the merged interface includes all fields. You can then manually mark missing fields as optional in the generated output.

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

The converter merges both objects and generates an interface with all three fields (id, name, role). The role field should be marked optional if it is not always present.

Best Practices for TypeScript Types

• Name interfaces meaningfully: Use the root name field in this tool to give your interfaces descriptive names like ApiResponse, UserProfile, or OrderItem instead of generic names.
• Colocate types with usage: Place generated interfaces near the code that uses them. If a type is used by multiple files, put it in a shared types/ directory.
• Validate at runtime too: TypeScript types only exist at compile time. For data from external sources (APIs, user input), use a runtime validation library like Zod or Yup alongside your TypeScript types.
• Keep types in sync: When the upstream API changes, regenerate your interfaces from fresh sample data. Stale types are worse than no types because they give false confidence.
• Use strict null checks: Enable strictNullChecks in your tsconfig.json to catch potential null/undefined errors. This works hand-in-hand with proper interface definitions.

How This Tool Works

This converter runs entirely in your browser. When you click “Convert to TypeScript,” the tool parses your JSON input using the native JSON.parse() method, then recursively traverses the data structure to generate interface definitions. No data is sent to any server.

The conversion algorithm handles edge cases like empty arrays (typed as unknown[]), null values (typed as null), and property keys that require quoting (keys with spaces or special characters are wrapped in quotes).

Frequently Asked Questions

Does this tool handle deeply nested JSON?

Yes. The converter recursively processes nested objects to any depth, generating a separate interface for each object level. Each interface is named based on its parent property key.

What happens with null values in JSON?

JSON null values are typed as null in the generated interface. In practice, you may want to change these to the expected type with | null (e.g., string | null) based on your API documentation.

Can I generate types instead of interfaces?

This tool generates interface declarations for objects and type aliases for top-level arrays or primitives. For most use cases, interfaces are the recommended choice for object shapes in TypeScript.

Is my JSON data sent to a server?

No. All processing happens locally in your browser using JavaScript. Your data never leaves your device. You can verify this by disconnecting from the internet — the tool continues to work.

How do I handle optional fields in the generated output?

Enable the “Make all fields optional” toggle to add ? to every property. Alternatively, you can selectively edit the generated output to mark only specific fields as optional.

What if my JSON keys contain special characters?

Keys that are not valid JavaScript identifiers (containing spaces, hyphens, or starting with numbers) are automatically quoted in the generated interface, e.g., "my-key": string.