JavaScript Date toJSON() Method

What You’ll Learn

toJSON() is how JavaScript Date objects become JSON-safe strings. It powers automatic date conversion in JSON.stringify and returns the same UTC ISO format as toISOString(). This guide covers syntax, stringify behavior, round-trip parsing, and error handling.

Introduction

JSON cannot store real Date objects—only strings, numbers, booleans, arrays, and plain objects. When you save or send dates over HTTP, you need a reliable text format. toJSON() bridges that gap by converting a Date into a portable UTC ISO string.

You rarely need to call it manually: JSON.stringify invokes toJSON() on every value that defines it. For dates, the result matches toISOString(). To read values back, pair with Date.parse() or the new Date(isoString) constructor after JSON.parse.

Understanding the toJSON() Method

Date.prototype.toJSON() exists specifically for JSON serialization. The built-in implementation returns this.toISOString(), producing strings like 2026-03-15T12:30:45.500Z.

• Explicit call — date.toJSON() returns the ISO string directly.
• Automatic call — JSON.stringify({ createdAt: date }) calls toJSON() on the Date while building JSON.
• Read-only — the original Date object is not modified.
• Invalid dates — throw RangeError, which also breaks JSON.stringify on that value.

📝 Syntax

dateObj.toJSON()

Parameters

• None. (The JSON spec allows a key argument when stringify calls toJSON; Date ignores it.)

Return value

• A UTC ISO 8601 string—the same output as toISOString() for valid dates.
• Throws RangeError: Invalid time value if the Date is invalid.

Examples Gallery

Open DevTools Console (F12) or use Try-it links. Fixed examples use Date.UTC() for predictable UTC output.

const date = new Date(Date.UTC(2026, 2, 15, 12, 0, 0));
const jsonDate = date.toJSON();

console.log(jsonDate); // "2026-03-15T12:00:00.000Z"

2026-03-15T12:00:00.000Z

const event = {
  name: "Launch Party",
  date: new Date(Date.UTC(2026, 2, 15, 18, 30, 0))
};

const jsonString = JSON.stringify(event);
console.log(jsonString);
// {"name":"Launch Party","date":"2026-03-15T18:30:00.000Z"}

{"name":"Launch Party","date":"2026-03-15T18:30:00.000Z"}

const date = new Date(Date.UTC(2026, 2, 15, 12, 0, 0));

console.log(date.toJSON());       // JSON hook
console.log(date.toISOString());  // explicit ISO
console.log(date.toJSON() === date.toISOString()); // true

2026-03-15T12:00:00.000Z
2026-03-15T12:00:00.000Z
true

const user = {
  name: "John Doe",
  birthdate: new Date(Date.UTC(1990, 4, 20))
};

const json = JSON.stringify(user);
const parsed = JSON.parse(json);
const restored = new Date(parsed.birthdate);

console.log(json);
console.log(restored.toJSON()); // same instant as original

{"name":"John Doe","birthdate":"1990-05-20T00:00:00.000Z"}
1990-05-20T00:00:00.000Z

const bad = new Date("not-a-date");

if (Number.isNaN(bad.getTime())) {
  console.log("Skip invalid date in JSON payload");
} else {
  console.log(JSON.stringify({ at: bad }));
}

Skip invalid date in JSON payload

🚀 Common Use Cases

• REST API bodies — fetch with JSON.stringify converts Date fields automatically.
• localStorage / sessionStorage — persist objects with date properties as JSON text.
• Database JSON columns — store ISO strings produced by toJSON().
• Logging pipelines — structured logs with ISO timestamps in JSON lines.
• Unit tests — assert JSON.stringify(model) contains expected ISO values.
• Microservice messages — event envelopes with occurredAt as portable UTC text.

📝 Notes

• toJSON() output equals toISOString() for standard Date objects.
• Read-only: does not mutate the Date.
• JSON.stringify on an array of dates converts each element via toJSON().
• After JSON.parse, date fields are strings—wrap with new Date() to use Date methods again.
• Invalid dates throw RangeError—validate before stringify in production code.
• For numeric JSON timestamps, store getTime() instead of relying on toJSON().

💡 Best Practices