Please support this book: buy it or donate

41. Creating and parsing JSON (JSON)

JSON (“JavaScript Object Notation”) is a storage format that uses text to encode data. Its syntax is a subset of JavaScript expressions. As an example, consider the following data, stored as text in a file jane.json:

  1. {
  2.   "first": "Jane",
  3.   "last": "Porter",
  4.   "married": true,
  5.   "born": 1890,
  6.   "friends": [ "Tarzan", "Cheeta" ]
  7. }

JavaScript has the global namespace object JSON provides methods for creating and parsing JSON.

41.1. The discovery and standardization of JSON

A specification for JSON was published by Douglas Crockford in 2001, at json.org. He explains:

I discovered JSON. I do not claim to have invented JSON, because it already existed in nature. What I did was I found it, I named it, I described how it was useful. I don’t claim to be the first person to have discovered it; I know that there are other people who discovered it at least a year before I did. The earliest occurrence I’ve found was, there was someone at Netscape who was using JavaScript array literals for doing data communication as early as 1996, which was at least five years before I stumbled onto the idea.

Later, JSON was standardized as ECMA-404:

  • 1st edition: October 2013
  • 2nd edition: December 2017

41.1.1. JSON’s grammar is frozen

Quoting the ECMA-404 standard:

Because it is so simple, it is not expected that the JSON grammar will ever change. This gives JSON, as a foundational notation, tremendous stability.

Therefore, JSON will never get improvements such as optional trailing commas, comments or unquoted keys – independently of whether or not they are considered desirable. However, that still leaves room for creating supersets of JSON that compile to plain JSON.

41.2. JSON syntax

JSON consists of the following parts of JavaScript:

  • Compound:
    • Object literals:
      • Keys are double-quoted strings.
      • Values are JSON values.
      • No trailing commas are allowed.
    • Array literals:
      • Elements are JSON values.
      • No holes or trailing commas are allowed.
  • Atomic:
    • null (but not undefined)
    • Booleans
    • Numbers (excluding NaN, +Infinity, -Infinity)
    • Strings (must be double-quoted)
      As a consequence, you can’t (directly) represent cyclic structures in JSON.

41.3. Using the JSON API

The global namespace object JSON contains methods for working with JSON data.

41.3.1. JSON.stringify(value, replacer?, space?)

.stringify() converts a JavaScript value to a JSON string.

41.3.1.1. Result: a single line of text

If you only provide the first argument, .stringify() returns a single line of text:

  1. assert.equal(
  2.   JSON.stringify({foo: ['a', 'b']}),
  3.   `{"foo":["a","b"]}`);
41.3.1.2. Result: a tree of indented lines

If you provide a non-negative integer for space (we are ignoring replacer here, which is explained later), then .stringify() returns one or more lines and indents by space spaces per level of nesting:

  1. assert.equal(
  2. JSON.stringify({foo: ['a', 'b']}, null, 2),
  3. `{
  4.   "foo": [
  5.     "a",
  6.     "b"
  7.   ]
  8. }`);
41.3.1.3. Details on how JavaScript values are stringified

Supported primitive values are stringified as expected:

  1. > JSON.stringify('abc')
  2. '"abc"'
  3. > JSON.stringify(123)
  4. '123'
  5. > JSON.stringify(null)
  6. 'null'

Non-finite numbers (incl. NaN) are stringified as 'null':

  1. > JSON.stringify(NaN)
  2. 'null'
  3. > JSON.stringify(Infinity)
  4. 'null'

Unsupported primitive values are stringified as undefined:

  1. > JSON.stringify(undefined)
  2. undefined
  3. > JSON.stringify(Symbol())
  4. undefined

Functions are stringified as undefined:

  1. > JSON.stringify(() => {})
  2. undefined

In an Array, elements that would be stringified as undefined, are stringified as 'null':

  1. > JSON.stringify([undefined, 123, () => {}])
  2. '[null,123,null]'

In an object (that is neither an Array nor a function), properties, whose values would be stringified as undefined, are skipped:

  1. > JSON.stringify({a: Symbol(), b: true})
  2. '{"b":true}'

If an object (which may be an Array or a function) has a method .toJSON(), then the result of that method is stringified, instead of the object. For example, Dates have a method .toJSON() that returns strings.

  1. > JSON.stringify({toJSON() {return true}})
  2. 'true'
  3. > JSON.stringify(new Date(2999, 11, 31))
  4. '"2999-12-30T23:00:00.000Z"'

For more details on stringification, consult the ECMAScript specification.

41.3.2. JSON.parse(text, reviver?)

.parse() converts a JSON text to a JavaScript value:

  1. > JSON.parse('{"foo":["a","b"]}')
  2. { foo: [ 'a', 'b' ] }

The parameter reviver is explained later.

41.3.3. Example: converting to and from JSON

The following class demonstrates one technique for implementing the conversion from and to JSON:

  1. class Point {
  2.   static fromJson(jsonObj) {
  3.     return new Point(jsonObj.x, jsonObj.y);
  4.   }
  6.   constructor(x, y) {
  7.     this.coord = [x, y];
  8.   }
  9.   
  10.   toJSON() {
  11.     const [x, y] = this.coord;
  12.     return {x, y};
  13.   }
  14. }
  15. assert.equal(
  16.   JSON.stringify(new Point(3, 5)),
  17.   '{"x":3,"y":5}');
  18. assert.deepEqual(
  19.   Point.fromJson(JSON.parse('{"x":3,"y":5}')),
  20.   new Point(3, 5));

The previously mentioned method .toJSON() is used when stringifying instances of Point.

41.4. Configuring what is stringified or parsed (advanced)

What is stringified or parsed, can be configured as follows:

  • .stringify() has the optional parameter replacer that contains either:
    • An Array with names of properties. When stringifying an object (that may be nested) only those properties will be considered, all others will be ignored.
    • A value visitor – a function that can transform JavaScript values before they are stringified.
  • .parse() has the optional parameter reviver – a value visitor that can transform the parsed JSON data before it is returned.

41.4.1. .stringfy(): specifying the only properties that objects should have

If the second parameter of .stringify() is an Array, then only object properties, whose names are mentioned in the Array, are included in the result:

  1. const obj = {
  2.   a: 1,
  3.   b: {
  4.     c: 2,
  5.     d: 3,
  6.   }
  7. };
  8. assert.equal(
  9.   JSON.stringify(obj, ['b', 'c']),
  10.   '{"b":{"c":2}}');

41.4.2. .stringify() and .parse(): value visitors

What I call a value visitor is a function that transforms JavaScript values (compound or atomic):

  • JSON.stringify() calls the value visitor in its parameter replacer before it stringfies the JavaScript value it received.
  • JSON.parse() calls the value visitor in its parameter reviver after it parsed the JSON data.
    A JavaScript value is transformed as follows: The value is either atomic or compound and contains more values (nested in Arrays and objects). The atomic value or the nested values are fed to the value vistor, one at a time. Depending on what the visitor returns, the current value is removed, changed or preserved.

A value visitor has the following type signature:

  1. type ValueVisitor = (this: object, key: string, value: any) => any;

The parameters are:

  • value: The current value.
  • this: Parent of current value. The parent of the root value r is {'': r}.

  • key: Key or index of the current value inside its parent. The empty string is used for the root value.
    The value visitor can return:

  • value: means there won’t be any change.

  • A different value x: leads to value being replaced with x.
  • undefined: leads to value being removed.

41.4.3. Example: visiting values

The following code demonstrates in which order a value visitor sees values.

  1. const log = [];
  2. function valueVisitor(key, value) {
  3.   log.push({key, value, this: this});
  4.   return value; // no change
  5. }
  7. const root = {
  8.   a: 1,
  9.   b: {
  10.     c: 2,
  11.     d: 3,
  12.   }
  13. };
  14. JSON.stringify(root, valueVisitor);
  15. assert.deepEqual(log, [
  16.   { key: '',  value: root,   this: { '': root } },
  17.   { key: 'a', value: 1,      this: root         },
  18.   { key: 'b', value: root.b, this: root         },
  19.   { key: 'c', value: 2,      this: root.b       },
  20.   { key: 'd', value: 3,      this: root.b       },
  21. ]);

As you can see, .stringify() visits values top-down (root first, leaves last). In contrast, .parse() visits values bottom-up (leaves first, root last).

41.4.4. Example: stringifying unsupported values

.stringify() has no special support for regular expression objects – it stringifies them as if they were plain objects:

  1. const obj = {
  2.   name: 'abc',
  3.   regex: /abc/ui,
  4. };
  5. assert.equal(
  6.   JSON.stringify(obj),
  7.   '{"name":"abc","regex":{}}');

We can fix that via a replacer:

  1. function replacer(key, value) {
  2.   if (value instanceof RegExp) {
  3.     return {
  4.       __type__: 'RegExp',
  5.       source: value.source,
  6.       flags: value.flags,
  7.     };
  8.   } else {
  9.     return value; // no change
  10.   }
  11. }
  12. assert.equal(
  13. JSON.stringify(obj, replacer, 2),
  14. `{
  15.   "name": "abc",
  16.   "regex": {
  17.     "__type__": "RegExp",
  18.     "source": "abc",
  19.     "flags": "iu"
  20.   }
  21. }`);

41.4.5. Example: parsing unsupported values

To .parse() the result from the previous section, we need a reviver:

  1. function reviver(key, value) {
  2.   // Very simple check
  3.   if (value && value.__type__ === 'RegExp') {
  4.     return new RegExp(value.source, value.flags);
  5.   } else {
  6.     return value;
  7.   }
  8. }
  9. const str = `{
  10.   "name": "abc",
  11.   "regex": {
  12.     "__type__": "RegExp",
  13.     "source": "abc",
  14.     "flags": "iu"
  15.   }
  16. }`;
  17. assert.deepEqual(
  18.   JSON.parse(str, reviver),
  19.   {
  20.     name: 'abc',
  21.     regex: /abc/ui,
  22.   });

41.5. FAQ

41.5.1. Why doesn’t JSON support comments?

Douglas Crockford explains why in a Google+ post from 1 May 2012:

I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability. I know that the lack of comments makes some people sad, but it shouldn’t.Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin [a minifier for JavaScript] before handing it to your JSON parser.

41.6. Quick reference: JSON

Signature of value visitors:

  1. type ValueVisitor = (this: object, key: string, value: any) => any;

JSON:

  • .stringify(value: any, replacer?: ValueVisitor, space?: string | number): string [ES5]

Convert value to a JSON string. The parameter replacer is explained earlier in this chapter. The parameter space works as follows:

  • If space is omitted, .stringify() returns a single line of text.
  1. assert.equal(
  2.   JSON.stringify({foo: 1, bar: [2, 3]}),
  3.   '{"foo":1,"bar":[2,3]}');
  • If space is a number, .stringify() returns one or more lines and indents them by space spaces per level of nesting.
  1. assert.equal(
  2. JSON.stringify({foo: 1, bar: [2, 3]}, null, 2),
  3. `{
  4.   "foo": 1,
  5.   "bar": [
  6.     2,
  7.     3
  8.   ]
  9. }`);
  • If space is a string, it is used to indent.
  1. assert.equal(
  2. JSON.stringify({foo: 1, bar: [2, 3]}, null, '>>'),
  3. `{
  4. >>"foo": 1,
  5. >>"bar": [
  6. >>>>2,
  7. >>>>3
  8. >>]
  9. }`);
  • .stringify(value: any, replacer?: (number | string)[] | null, space?: string | number): string [ES5]

If replacer is an Array, then the result only includes object properties whose names are mentioned in the Array.

  1. > JSON.stringify({foo: 1, bar: 2}, ['foo'])
  2. '{"foo":1}'
  • .parse(text: string, reviver?: ValueVisitor): any [ES5]

Parse the JSON inside text and return a JavaScript value. The parameter reviver is explained earlier in this chapter.

  1. assert.deepEqual(
  2.   JSON.parse('{"a":true,"b":[1,2]}'),
  3.   { a: true, b: [1,2] }
  4. );

41.6.1. Sources