JSON methods, toJSON

Let’s say we have a complex object, and we’d like to convert it into a string, to send it over a network, or just to output it for logging purposes.

Naturally, such a string should include all important properties.

We could implement the conversion like this:

But in the process of development, new properties are added, old properties are renamed and removed. Updating such toString every time can become a pain. We could try to loop over properties in it, but what if the object is complex and has nested objects in properties? We’d need to implement their conversion as well. And, if we’re sending the object over a network, then we also need to supply the code to “read” our object on the receiving side.

Luckily, there’s no need to write the code to handle all this. The task has been solved already.


The JSON (JavaScript Object Notation) is a general format to represent values and objects. It is described as in RFC 4627 standard. Initially it was made for JavaScript, but many other languages have libraries to handle it as well. So it’s easy to use JSON for data exchange when the client uses JavaScript and the server is written on Ruby/PHP/Java/Whatever.

JavaScript provides methods:

  • JSON.stringify to convert objects into JSON.
  • JSON.parse to convert JSON back into an object.

For instance, here we JSON.stringify a student:

The method JSON.stringify(student) takes the object and converts it into a string.

The resulting json string is a called JSON-encoded or serialized or stringified or marshalled object. We are ready to send it over the wire or put into plain data store.

Please note that JSON-encoded object has several important differences from the object literal:

  • Strings use double quotes. No single quotes or backticks in JSON. So 'John' becomes "John".
  • Object property names are double-quoted also. That’s obligatory. So age:30 becomes "age":30.

JSON.stringify can be applied to primitives as well.

Natively supported JSON types are:

  • Objects { ... }
  • Arrays [ ... ]
  • Primitives:
    • strings,
    • numbers,
    • boolean values true/false,
    • null.

For instance:

JSON is data-only cross-language specification, so some JavaScript-specific object properties are skipped by JSON.stringify.


  • Function properties (methods).
  • Symbolic properties.
  • Properties that store undefined.

Usually that’s fine. If that’s not what we want, then soon we’ll see how to customize the process.

The great thing is that nested objects are supported and converted automatically.

For instance:

The important limitation: there must be no circular references.

For instance:

Here, the conversion fails, because of circular reference: room.occupiedBy references meetup, and meetup.place references room:

Excluding and transforming: replacer

The full syntax of JSON.stringify is:

A value to encode.
Array of properties to encode or a mapping function function(key, value).
Amount of space to use for formatting

Most of time, JSON.stringify is used with first argument only. But if we need to fine-tune the replacement process, like to filter out circular references, we can use the second argument of JSON.stringify.

If we pass an array of properties to it, only these properties will be encoded.

For instance:

Here we are probably too strict. The property list is applied to the whole object structure. So participants are empty, because name is not in the list.

Let’s include every property except room.occupiedBy that would cause the circular reference:

Now everything except occupiedBy is serialized. But the list of properties is quite long.

Fortunately, we can use a function instead of an array as the replacer.

The function will be called for every (key,value) pair and should return the “replaced” value, which will be used instead of the original one.

In our case, we can return value “as is” for everything except occupiedBy. To ignore occupiedBy, the code below returns undefined:

Please note that replacer function gets every key/value pair including nested objects and array items. It is applied recursively. The value of this inside replacer is the object that contains the current property.

The first call is special. It is made using a special “wrapper object”: {"": meetup}. In other words, the first (key,value) pair has an empty key, and the value is the target object as a whole. That’s why the first line is ":[object Object]" in the example above.

The idea is to provide as much power for replacer as possible: it has a chance to analyze and replace/skip the whole object if necessary.

Formatting: spacer

The third argument of JSON.stringify(value, replacer, spaces) is the number of spaces to use for pretty formatting.

Previously, all stringified objects had no indents and extra spaces. That’s fine if we want to send an object over a network. The spacer argument is used exclusively for a nice output.

Here spacer = 2 tells JavaScript to show nested objects on multiple lines, with indentation of 2 spaces inside an object:

The spaces parameter is used solely for logging and nice-output purposes.

Custom “toJSON”

Like toString for a string conversion, an object may provide method toJSON for to-JSON conversion. JSON.stringifyautomatically calls it if available.

For instance:

Here we can see that date (1) became a string. That’s because all dates have a built-in toJSON method which returns such kind of string.

Now let’s add a custom toJSON for our object room:

As we can see, toJSON is used both for the direct call JSON.stringify(room) and for the nested object.


To decode a JSON-string, we need another method named JSON.parse.

The syntax:

JSON-string to parse.
Optional function(key,value) that will be called for each (key,value) pair and can transform the value.

For instance:

Or for nested objects:

The JSON may be as complex as necessary, objects and arrays can include other objects and arrays. But they must obey the format.

Here are typical mistakes in hand-written JSON (sometimes we have to write it for debugging purposes):

Besides, JSON does not support comments. Adding a comment to JSON makes it invalid.

There’s another format named JSON5, which allows unquoted keys, comments etc. But this is a standalone library, not in the specification of the language.

The regular JSON is that strict not because its developers are lazy, but to allow easy, reliable and very fast implementations of the parsing algorithm.

Using reviver

Imagine, we got a stringified meetup object from the server.

It looks like this:

And now we need to deserialize it, to turn back into JavaScript object.

Let’s do it by calling JSON.parse:

Whoops! An error!

The value of meetup.date is a string, not a Date object. How could JSON.parse know that it should transform that string into a Date?

Let’s pass to JSON.parse the reviving function that returns all values “as is”, but date will become a Date:

By the way, that works for nested objects as well:


  • JSON is a data format that has its own independent standard and libraries for most programming languages.
  • JSON supports plain objects, arrays, strings, numbers, booleans and null.
  • JavaScript provides methods JSON.stringify to serialize into JSON and JSON.parse to read from JSON.
  • Both methods support transformer functions for smart reading/writing.
  • If an object has toJSON, then it is called by JSON.stringify.
Spread the love
  • 15
  • 15

Leave a Reply

Your email address will not be published. Required fields are marked *