Runnable TypeScript Docs: JSON

Q: What type does JSON.parse return in TypeScript?

any. The compiler cannot know what a string contains, so const user: User = JSON.parse(text) compiles whatever the text holds. Assign the result to unknown and validate it when the data comes from outside your program.

Q: How do I import a JSON file in TypeScript?

import config from "./config.json"; works in TypeScript 7 with module set to nodenext, node20, commonjs, esnext or preserve, and the result is typed from the file's contents. With node16 or node18, also set "resolveJsonModule": true. In an ES module under nodenext or node20, add the attribute Node requires: import config from "./config.json" with { type: "json" };.

Q: Does JSON.stringify always return a string?

Its type says string, but JSON.stringify(undefined) and JSON.stringify(() => 1) return undefined at run time. Values inside objects are converted too: a Date becomes an ISO string, and Map and Set become {}.

JSON.parse returns any, so TypeScript accepts any type you assign the result to. That makes typing parsed JSON one line, and it also means the type is a promise you make, not something the compiler checks:

interface User {
  name: string;
  age: number;
}

const text = '{"name":"Ada","age":36}';
const user: User = JSON.parse(text); // JSON.parse returns any

console.log(user.name.toUpperCase(), user.age + 1); // ADA 37

// The annotation is a promise, not a check:
const wrong: User = JSON.parse('{"name":"Bob","age":"41"}');
console.log(wrong.age + 1); // 411, a string concatenation

The second object has age as the string "41". TypeScript still calls it a number, because any can be assigned to anything, and the program prints 411. For JSON your own code wrote a moment ago, the annotation is fine. For data from a request, a file or local storage, validate it.

Parse into unknown

Typing the result as unknown makes the compiler insist on a check before any property is used:

// This does not compile: unknown must be narrowed before use.
const data: unknown = JSON.parse('{"name":"Ada"}');

console.log(data.name);

The error is index.ts(4,13): error TS18046: 'data' is of type 'unknown'. Every check you then write narrows data a little further.

Validate with a Type Guard

A type guard is a function returning value is User. When it returns true, TypeScript treats the value as a User from then on, and the checks inside it are real run-time checks:

interface User {
  name: string;
  age: number;
}

function isUser(value: unknown): value is User {
  return (
    typeof value === "object" &&
    value !== null &&
    "name" in value &&
    typeof value.name === "string" &&
    "age" in value &&
    typeof value.age === "number"
  );
}

function parseUser(text: string): User {
  const data: unknown = JSON.parse(text);
  if (!isUser(data)) {
    throw new Error("Not a valid user: " + text);
  }
  return data; // narrowed to User
}

console.log(parseUser('{"name":"Ada","age":36}')); // { name: 'Ada', age: 36 }
try {
  parseUser('{"name":"Bob","age":"41"}');
} catch (e) {
  console.log(e instanceof Error ? e.message : e); // Not a valid user: {"name":"Bob","age":"41"}
}

JSON.parse itself throws a SyntaxError on malformed text, so real code wraps it in try/catch as well. For large or nested payloads, hand-written guards get long; schema libraries such as Zod or Valibot let you declare the shape once and derive both the validator and the TypeScript type from it.

JSON to TypeScript Interface

Converting a JSON sample into types is mechanical. Given this response:

{
    "id": 42,
    "title": "Learn TypeScript",
    "done": false,
    "owner": { "id": 7, "name": "Ada" },
    "tags": ["study", "ts"],
    "dueDate": "2024-03-15T10:30:00Z",
    "notes": null
}

Map each value to its type, give nested objects their own interface, and mark what can vary:

interface Owner {
  id: number;
  name: string;
}

interface Task {
  id: number;
  title: string;
  done: boolean;
  owner: Owner;         // nested object: its own interface
  tags: string[];       // array of strings
  dueDate: string;      // JSON has no dates: it is an ISO string
  notes: string | null; // null in this sample, text in others
  priority?: number;    // missing in this sample, present in others
}

const task: Task = {
  id: 42,
  title: "Learn TypeScript",
  done: false,
  owner: { id: 7, name: "Ada" },
  tags: ["study", "ts"],
  dueDate: "2024-03-15T10:30:00Z",
  notes: null,
};

console.log(task.owner.name, task.tags.length, task.priority ?? "none"); // Ada 2 none

A single sample cannot tell you which fields are optional or nullable. Look at several responses, or the API's documentation, before settling on ? and | null.

Dates and the Reviver

JSON has no date type, so dates arrive as strings. The second argument of JSON.parse, the reviver, is called for every key and can rebuild them:

interface Order {
  id: number;
  placedAt: Date;
}

const text = '{"id":7,"placedAt":"2024-03-15T10:30:00.000Z"}';

const order: Order = JSON.parse(text, (key, value) =>
  key === "placedAt" ? new Date(value) : value
);

console.log(order.placedAt instanceof Date, order.placedAt.getUTCHours()); // true 10
console.log(JSON.stringify(order, null, 2));

The reviver's value parameter is any, and so is the result, so the Order type is still trusted rather than checked. JSON.stringify(order, null, 2) indents the output by two spaces and turns the Date back into its ISO string.

JSON.stringify and What It Loses

JSON.stringify is typed to return string. The values it converts do not always come back the same, and the type does not warn you:

interface Meeting {
  title: string;
  at: Date;
  tags: Set<string>;
}

const meeting: Meeting = {
  title: "Launch",
  at: new Date("2024-03-15T10:30:00Z"),
  tags: new Set(["release"]),
};

const json = JSON.stringify(meeting);
console.log(json); // {"title":"Launch","at":"2024-03-15T10:30:00.000Z","tags":{}}

const back = JSON.parse(json);
console.log(typeof back.at, back.tags); // string {}

const nothing: string = JSON.stringify(undefined); // typed string...
console.log(nothing); // ...but the value is undefined

Value	After `JSON.stringify`
`Date`	ISO string (via its `toJSON` method)
`Map`, `Set`	`{}` (convert with `[...set]` or `Object.fromEntries(map)` first)
`undefined`, functions, symbols in an object	the key is left out
`undefined`, functions, symbols in an array	`null`
`undefined`, a function or a symbol on its own	`undefined`, not a string
`NaN`, `Infinity`	`null`
`bigint`	throws a `TypeError`

The run-time rules are the same as in plain JavaScript, covered in JSON in JavaScript.

A Type for Any JSON Value

When code handles arbitrary JSON, a recursive type describes exactly what JSON can hold and rejects values it cannot:

type JsonValue =
  | string
  | number
  | boolean
  | null
  | JsonValue[]
  | { [key: string]: JsonValue };

function countLeaves(value: JsonValue): number {
  if (Array.isArray(value)) {
    return value.reduce((n: number, v) => n + countLeaves(v), 0);
  }
  if (typeof value === "object" && value !== null) {
    return Object.values(value).reduce((n: number, v) => n + countLeaves(v), 0);
  }
  return 1;
}

const doc: JsonValue = { name: "Ada", langs: ["en", "fr"], address: { city: "London", zip: null } };
console.log(countLeaves(doc)); // 5

// @ts-expect-error a Date is not a JSON value
const bad: JsonValue = { at: new Date() };

Without the comment, the last line is a compile error because a Date object is not a JsonValue.

Importing .json Files

A .json file can be imported like a module, and TypeScript infers its type from the contents:

{ "name": "app", "port": 8080, "tags": ["a"] }

// CommonJS output, or a bundler
import config from "./config.json";
const port: number = config.port; // typed from the file: number

// An ES module under module: nodenext
import settings from "./config.json" with { type: "json" };

In TypeScript 7 this works without extra settings for module set to nodenext, node20, commonjs, esnext or preserve. Under node16 and node18 it fails with error TS2732, Cannot find module './config.json'. Consider using '--resolveJsonModule' to import module with '.json' extension., until you add "resolveJsonModule": true; setting it to false turns JSON imports off everywhere. In an ES module under nodenext or node20, the import needs the with { type: "json" } attribute (error TS1543 without it) and only the default import is allowed (error TS1544 for import { port }). tsc copies the imported .json file to outDir next to the compiled JavaScript.

Frequently Asked Questions

What type does JSON.parse return in TypeScript?

any. The compiler cannot know what a string contains, so const user: User = JSON.parse(text) compiles whatever the text holds. Assign the result to unknown and validate it when the data comes from outside your program.

How do I convert JSON to a TypeScript interface?

Take a representative sample and write one property per key: strings, numbers and booleans map to string, number and boolean, a nested object becomes its own interface, an array of objects becomes Item[], and keys that are sometimes missing get ?. Code generators such as quicktype automate this, but check their guesses against more than one sample.

How do I import a JSON file in TypeScript?

import config from "./config.json"; works in TypeScript 7 with module set to nodenext, node20, commonjs, esnext or preserve, and the result is typed from the file's contents. With node16 or node18, also set "resolveJsonModule": true. In an ES module under nodenext or node20, add the attribute Node requires: import config from "./config.json" with { type: "json" };.

Does JSON.stringify always return a string?

Its type says string, but JSON.stringify(undefined) and JSON.stringify(() => 1) return undefined at run time. Values inside objects are converted too: a Date becomes an ISO string, and Map and Set become {}.

Related concepts