Tiny language and engine for selecting specific parts of a JS object, hiding the rest.
Switch branches/tags
Nothing to show
Clone or download
Pull request Compare This branch is 36 commits behind nemtsov:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


JSON Mask Build Status NPM version

This is a tiny language and an engine for selecting specific parts of a JS object, hiding/masking the rest.

var mask = require('json-mask')
mask({p: {a: 1, b: 2}, z: 1}, 'p/a,z')  // {p: {a: 1}, z: 1}

The main difference between JSONPath / JSONSelect and this engine is that JSON Mask preserves the structure of the original input object. Instead of returning an array of selected sub-elements (e.g. [{a: 1}, {z: 1}] from example above), it filters-out the parts of the object that you don't need, keeping the structure unchanged: {p: {a: 1}, z: 1}.

This is important because JSON Mask was designed with HTTP resources in mind, the structure of which I didn't want to change after the unwanted fields were masked / filtered.

If you've used the Google APIs, and provided a ?fields= query-string to get a Partial Response, you've already used this language. The desire to have partial responses in my own Node.js-based HTTP services was the reason I wrote JSON Mask.

For express users, there's an express-partial-response middleware. It will integrate with your existing services with no additional code if you're using res.json() or res.jsonp().

This library has no dependencies. It works in Node as well as in the browser:

browser support

Note: the 1.5KB (gz), or 4KB (uncompressed) browser build is in the /build folder.


The syntax is loosely based on XPath:

  • a,b,c comma-separated list will select multiple fields
  • a/b/c path will select a field from its parent
  • a(b,c) sub-selection will select many fields from a parent
  • a/*/c the star * wildcard will select all items in a field

Take a look at test/index-test.js for examples of all of these and more.


  Props ::= Prop | Prop "," Props
   Prop ::= Object | Array
 Object ::= NAME | NAME "/" Object
  Array ::= NAME "(" Props ")"
   NAME ::= ? all visible characters ?


Identify the fields you want to keep:

var fields = 'url,object(content,attachments/url)'

From this sample object:

var originalObj = {
  id: 'z12gtjhq3qn2xxl2o224exwiqruvtda0i',
  url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  object: {
    objectType: 'note',
    content: 'A picture... of a space ship... launched from earth 40 years ago.',
    attachments: [{
      objectType: 'image',
      url: 'http://apod.nasa.gov/apod/ap110908.html',
      image: {height: 284, width: 506}
  provider: {title: 'Google+'}

Here's what you'll get back:

var expectObj = {
  url: 'https://plus.google.com/102817283354809142195/posts/F97fqZwJESL',
  object: {
    content: 'A picture... of a space ship... launched from earth 40 years ago.',
    attachments: [{
      url: 'http://apod.nasa.gov/apod/ap110908.html'

Let's test that:

var mask = require('json-mask')
  , assert = require('assert')
  , maskedObj

maskedObj = mask(originalObj, fields)

assert.deepEqual(maskedObj, expectObj)

Partial Responses Server Example

Here's an example of using json-mask to implement the Google API Partial Response

var http = require('http')
  , url = require('url')
  , mask = require('json-mask')
  , server

server = http.createServer(function (req, res) {
  var fields = url.parse(req.url, true).query.fields
    , data = {
          firstName: 'Mohandas'
        , lastName: 'Gandhi'
        , aliases: [{
              firstName: 'Mahatma'
            , lastName: 'Gandhi'
          }, {
              firstName: 'Bapu'
  res.writeHead(200, {'Content-Type': 'application/json'})
  res.end(JSON.stringify(mask(data, fields)))


Let's test it:

$ curl 'http://localhost:4000'

$ # Let's just get the first name
$ curl 'http://localhost:4000?fields=lastName'

$ # Now, let's just get the first names directly as well as from aliases
$ curl 'http://localhost:4000?fields=firstName,aliases(firstName)'

Note: a few more examples are in the /example folder.



  • //cdn.jsdelivr.net/jsonmask/0.1.1a/jsonMask.js
  • //cdn.jsdelivr.net/jsonmask/0.1.1a/jsonMask.min.js