Skip to main content
Castov
JSON & Schemas · 100% Client-Side Engine

JSON to TypeScript Interface & Type Converter

Convert JSON payloads into clean TypeScript interfaces or type aliases in browser. Extracts nested interfaces, merges optional array keys, and handles readonly modifiers.

JSON to TypeScript100% Client-Side Engine
Output Configuration Options
PascalCase identifier for the root TypeScript declaration
Choose between extendable interfaces or type aliases
Type assigned to JSON properties whose sample value is null
Flatten nested objects into standalone exported types
Prefix all generated properties with readonly
Input (json)27 lines
Output (typescript)25 lines

Example Output (JSON to TypeScript)

SAMPLE INPUT (JSON)
{
  "id": "ord_77410",
  "status": "completed",
  "totalCents": 14900,
  "currency": "USD",
  "isTaxExempt": false,
  "discountCode": null,
  "x-request-id": "req_99a81bc",
  "customer": {
    "id": "cus_301",
    "email": "elena.rostova@acme.dev",
    "tier": "enterprise"
  },
  "lineItems": [
    {
      "sku": "PRO-PLAN-ANNUAL",
      "quantity": 1,
      "unitPriceCents": 12000
    },
    {
      "sku": "ADDON-AUDIT-LOG",
      "quantity": 2,
      "unitPriceCents": 1450,
      "notes": "Priority provisioning"
    }
  ]
}
GENERATED OUTPUT (TYPESCRIPT)
export interface OrderResponse {
  id: string;
  status: string;
  totalCents: number;
  currency: string;
  isTaxExempt: boolean;
  discountCode: null;
  "x-request-id": string;
  customer: OrderResponseCustomer;
  lineItems: OrderResponseLineItem[];
}

export interface OrderResponseCustomer {
  id: string;
  email: string;
  tier: string;
}

export interface OrderResponseLineItem {
  notes?: string;
  quantity: number;
  sku: string;
  unitPriceCents: number;
}

Understanding the JSON to TypeScript Transformation

When integrating REST APIs, GraphQL responses, or static configuration files into a TypeScript project, manually writing interface definitions for deeply nested JSON objects is error-prone. A single missing optional modifier (?) on an inconsistent array element can trigger runtime TypeErrors when accessing undefined properties. This converter analyzes the structure of your JSON payload, extracts reusable sub-interfaces, and infers union and optional types.

Key Architectural Benefits

  • •Extracts deeply nested JSON objects into standalone, named PascalCase interfaces that can be imported directly into React props or service layers.
  • •Inspects every object inside an array rather than only the first element, marking keys missing in sibling items as optional (?).
  • •Automatically quotes non-standard property keys (such as HTTP headers like 'x-request-id' or kebab-case keys) so the output compiles without syntax errors.
  • •Uses unknown instead of any for empty arrays and untyped nulls, complying with strict @typescript-eslint/no-explicit-any rules.

Common Conversion Pitfalls & Fixes

⚠️ Pitfall: Assuming TypeScript interfaces validate API data at runtime
Solution: TypeScript interfaces and type aliases are completely erased during compilation. If an external API returns a number where your interface expects a string, TypeScript will not throw an error at runtime. If you need runtime payload verification, use our JSON to Zod converter.
⚠️ Pitfall: Inferring types from only the first element of an array
Solution: Naive converters only inspect array[0]. If array[1] contains an extra optional field or a nullable field, the generated type will be incomplete. Always inspect all elements in a sample array to detect optional properties.
⚠️ Pitfall: Using any[] for empty JSON arrays
Solution: Typing an empty array [] as any[] silently disables type checking whenever items are pushed or mapped. Use unknown[] until the element structure is known, forcing explicit type narrowing.

Verified Edge Cases & Complex Scenarios

Real payloads often contain edge cases that break naive generators. Here is how our engine handles them:

1. Heterogeneous Object Arrays (Optional Key Merging)

An array of objects where some elements include optional metadata fields that are absent in other elements.

INPUT (JSON)
[
  { "sku": "BASIC", "price": 10 },
  { "sku": "PRO", "price": 25, "coupon": "SAVE20" }
]
OUTPUT (TYPESCRIPT)
export type OrderResponse = OrderResponseItem[];

export interface OrderResponseItem {
  coupon?: string;
  price: number;
  sku: string;
}
Why: The engine scans all objects in the array, takes the union of all property keys, and appends the optional '?' modifier to keys that do not appear in every element.
2. Hyphenated & Special Character Keys

JSON payloads containing HTTP headers, namespace prefixes, or numeric keys that are invalid bare TypeScript identifiers.

INPUT (JSON)
{
  "content-type": "application/json",
  "@context": "https://schema.org",
  "200": "OK"
}
OUTPUT (TYPESCRIPT)
export interface HeadersMap {
  "200": string;
  "content-type": string;
  "@context": string;
}
Why: Keys that do not match standard ECMAScript identifier rules (/^[a-zA-Z_$][a-zA-Z0-9_$]*$/) are safely quoted with JSON.stringify.
3. Mixed Primitive Arrays (Union Types)

Arrays containing a mix of strings, numbers, or booleans.

INPUT (JSON)
{
  "coordinates": [40.7128, -74.006, "NYC"]
}
OUTPUT (TYPESCRIPT)
export interface LocationData {
  coordinates: (number | string)[];
}
Why: Instead of falling back to unknown[], distinct primitive types inside an array are combined into a parenthesized TypeScript union array.

Frequently Asked Questions

Should I generate a TypeScript 'interface' or a 'type' alias?
For object shapes, `export interface` is generally preferred because it supports declaration merging, `extends` clauses, and produces cleaner error messages in TypeScript compiler output. However, if your root JSON payload is a top-level array or primitive union, a `type` alias is required and generated automatically.
How are JSON null values typed, and when should I switch between 'null' and 'unknown'?
By default, properties with a `null` value in the JSON sample are typed strictly as `null` (e.g., `discountCode: null;`). If the property is an unpopulated field whose actual runtime type is not yet known from the sample, you can switch the Null Value Type option to `unknown` so it acts as a type-safe placeholder without resorting to `any`.
How does the 'Immutability (readonly)' option affect the output?
Enabling `readonly` prefixes every property with the `readonly` keyword (e.g., `readonly id: string;`). This prevents accidental mutation of API response objects in Redux state, React props, or functional pipelines at compile time.
Does this tool send my JSON payload to any server?
No. All JSON parsing and TypeScript AST generation happen 100% locally in your browser using pure JavaScript. Your API payloads never leave your machine.

Related Developer Converters

Browse All
JSON & Schemas

JSON to Zod Schema

Convert raw JSON into strict, production-ready Zod schemas. Supports ISO datetime offsets, email, URLs, nullish options, and inferred TypeScript types in browser.

Convert now
SQL & Database

SQL to Prisma Schema

Convert PostgreSQL and MySQL CREATE TABLE DDL statements into Prisma ORM models. Infers 1:1, 1:n, and n:m relations, enums, @default, @unique, and @@index.

Convert now
DevOps & Network

cURL to Fetch

Convert Chrome Copy as cURL commands into Browser Fetch, Node.js Fetch, or Axios code. Handles -H, -d, --data-raw, -u UTF-8 Basic Auth, -F FormData, -b, -L, and -k.

Convert now
Data Formats

YAML to JSON

Convert YAML configurations, Kubernetes manifests, and Docker Compose files to JSON in browser. Resolves anchors/aliases, multi-document streams, and YAML 1.2 vs 1.1 scalars.

Convert now