JSON 3 Polyfill

3.3.3 · deprecated · verified Sun Apr 19

JSON 3 was a polyfill designed to provide `JSON.parse` and `JSON.stringify` functionality for older JavaScript environments that lacked native JSON support, specifically targeting ECMAScript 5 and earlier platforms (e.g., Internet Explorer 6-8). It adheres closely to the ECMAScript 5.1 specification, notably employing a recursive descent parser to avoid reliance on `eval`, a common security concern in early JSON implementations. The library's core differentiator was its robust, specification-compliant parsing and stringification for these legacy environments. However, it explicitly deviates from the spec regarding date serialization: it does not define `Date#toISOString()` or `Date#toJSON()`, instead handling date objects internally during `stringify()` operations, serializing them as simplified ISO 8601 strings. This approach aimed to preserve CommonJS compatibility and avoid polluting native prototypes. The project, last updated to version 3.3.3, is now explicitly deprecated and unmaintained. Developers are strongly advised against using it in new projects and should migrate existing applications to leverage the native `JSON` object available in all modern JavaScript environments. Its release cadence was irregular towards the end, as native JSON support became widespread. It was part of the BestieJS family, focusing on cross-platform support and specification adherence.

Common errors

```
JSON.parse is not a function
```
cause Running in an older browser environment where native `JSON` is unavailable, and the `json3` polyfill has either not been loaded or failed to execute correctly.

fix Ensure the `json3` script is included in your HTML `<head>` or at the beginning of your JavaScript bundle, before any code that attempts to use `JSON.parse` or `JSON.stringify`. Verify that the script loaded without errors (check browser developer console).
```
Uncaught TypeError: Cannot read property 'stringify' of undefined
```
cause Attempting to use `JSON.stringify` (or `parse`) in a modular context (e.g., CommonJS or ESM) without `json3` correctly polyfilling the global `JSON` object, as `json3` is primarily designed for global script inclusion.

fix json3 is intended to be a global polyfill. Include it via a `<script>` tag in your HTML. If using a module bundler, ensure it processes the script in a way that exposes `JSON` globally (e.g., using `script-loader` for Webpack or similar global injection methods).
```
Date objects are not serialized as expected to ISO 8601 strings.
```
cause json3's custom date serialization logic does not rely on `Date#toJSON()` or `Date#toISOString()`, which can lead to different output formats compared to native `JSON.stringify()` or other polyfills.

fix If a specific ISO 8601 date string format is required, manually transform `Date` objects into the desired string format before passing them to `JSON.stringify`. For example, `JSON.stringify({ date: myDate.toISOString() })`.

Warnings

breaking The json3 package is officially deprecated and no longer maintained. Using it in new projects is strongly discouraged, and existing projects should migrate to native JSON functionality.
Fix: Remove json3 from your project. Rely on the native `window.JSON` object, which is universally available and performs better in all modern JavaScript environments. If targeting extremely old browsers (e.g., IE6-8) is an absolute requirement, carefully assess the risks of using unmaintained software.
gotcha JSON 3 does not define `Date#toISOString()` or `Date#toJSON()`, deviating from the ECMAScript specification. Date serialization is handled internally by its `stringify()` implementation, which can lead to inconsistencies if other parts of the application expect these methods to exist or behave differently.
Fix: Be aware of this specific behavior when serializing `Date` objects. If specific ISO 8601 formats are strictly required, consider manually transforming dates into strings before `stringify` operations, or ensure your target environments natively support `Date.prototype.toJSON` if you are using native JSON.
gotcha In environments where native `Date#toJSON()` implementations do not conform to the spec, JSON 3 will override the native `JSON.stringify()`. This can cause unexpected behavior or performance regressions if the native implementation was superior or if other code relies on the native `Date.toJSON` behavior.
Fix: Thoroughly test JSON serialization behavior across all target environments, especially regarding `Date` objects. If such overriding is problematic, consider conditionally loading the polyfill only when truly necessary, or adopt a different strategy for handling JSON in older browsers (e.g., server-side rendering for legacy clients).
gotcha As an unmaintained library, json3 will not receive security updates or bug fixes. Relying on it for critical applications in environments where native JSON is absent exposes your application to potential vulnerabilities or undefined behavior discovered post-deprecation.
Fix: Prioritize migrating away from json3. If immediate migration is impossible, thoroughly audit your application's use of JSON to minimize exposure, and consider isolating its usage to less sensitive parts of your application, acknowledging the inherent risks of unmaintained software.

Install

npm install json3 npm
yarn add json3 yarn
pnpm add json3 pnpm

Imports

JSON.parse
wrong:
```
import { parse } from 'json3'
```
correct:
```
JSON.parse('{"key":"value"}')
```
json3 is primarily a global polyfill. It overrides `window.JSON` directly when loaded via a `<script>` tag. No explicit import statement (ESM or CommonJS) is needed or intended for its core functionality.
JSON.stringify
wrong:
```
import { stringify } from 'json3'
```
correct:
```
JSON.stringify({ key: 'value' })
```
json3 is primarily a global polyfill. It overrides `window.JSON` directly when loaded via a `<script>` tag. No explicit import statement (ESM or CommonJS) is needed or intended for its core functionality.
JSON3.noConflict
wrong:
```
JSON.noConflict()
```
correct:
```
JSON3.noConflict()
```
When used in web browsers, json3 exposes an additional `JSON3` object. The `noConflict` method is available on this `JSON3` object, not the main `JSON` object which the polyfill potentially overrides.

Quickstart

This quickstart demonstrates how to include json3 as a global polyfill via a script tag and use its `JSON.stringify` and `JSON.parse` functions, including a reviver, and the `JSON3.noConflict` method.

<!-- Include json3 from a CDN in your HTML -->
<script src="//cdnjs.cloudflare.com/ajax/libs/json3/3.3.2/json3.min.js"></script>
<script>
  // After the script is loaded, JSON.parse and JSON.stringify will be available globally
  // They will polyfill the native JSON object if it's missing or incomplete in older browsers.
  const data = { "Hello": 123, "Nested": [4, 5, { "Date": new Date() }] };
  const jsonString = JSON.stringify(data, null, 2);
  console.log('Stringified JSON:', jsonString);
  // Expected output (date format might vary slightly based on environment):
  // Stringified JSON: {
  //   "Hello": 123,
  //   "Nested": [
  //     4,
  //     5,
  //     {
  //       "Date": "2026-04-19T07:42:00.000Z" // Example ISO 8601 format
  //     }
  //   ]
  // }

  const parsedData = JSON.parse(jsonString, function (key, value) {
    if (typeof value === "number") {
      return value % 2 ? "Odd" : "Even";
    }
    return value;
  });
  console.log('Parsed data with reviver:', parsedData);
  // Expected output:
  // Parsed data with reviver: { Hello: 'Odd', Nested: [ 'Even', 'Odd', { Date: '2026-04-19T07:42:00.000Z' } ] }

  // Using JSON3.noConflict() if you need to restore original window.JSON
  // and use JSON3 functions under a different namespace.
  const json3Restored = JSON3.noConflict();
  console.log('JSON object after noConflict:', typeof JSON); // Should show original JSON or undefined
  console.log('json3Restored.stringify:', json3Restored.stringify(data));
</script>

view raw JSON →