Merging Behaviour

__merge operations act upon the map the __merge item is inside. If __merge is not specified, default behavior occurs.

You must specify an empty __merge in the root map/object for merging behaviour to take place. This is only required for the root map.

In this document, maps are equivalent to objects, lists are equivalent to arrays.

Merge behaviour (default)

Lists

Adds new items.
Before Merge After 
{
  "list" : ["foo", "bar", "baz"]
}
          
{
  "__merge" : [],
  "list" : [ "foo", "qux" ]
}
          
{
  "list" : ["foo", "bar", "baz", "foo", "qux"]
}

Maps

Nested maps default to merge behaviour unless overriden. Adds new keys, replaces existing keys.
Before Merge After 
{
  "map" : {
    "foo" : "before",
    "baz" : "before"
  }
}
          
{
  "__merge" : [],
  "map" : {
    "foo" : "after",
    "bar" : "after"
  }
}
          
{
  "map" : {
    "baz" : "before",
    "foo" : "after",
    "bar" : "after"
  }
}

Everything else

Replaces value.
Before Merge After 
{
  "foo" : 0,
  "bar" : "before"
}
          
{
  "__merge" : [],
  "foo" : "after",
  "bar" : {
    "foo" : "after",
  },
  "baz" : 1,
  "qux" : "after"
}
          
{
  "foo" : "after",
  "bar" : {
    "foo" : "after",
  },
  "baz" : 1,
  "qux" : "after"
}

Delete behaviour ("delete", "overwrite")

Everything

Removes value. Useful when replacing the value of a list or map. You can use the name "overwrite" instead of "delete" to clarify that you are replacing a value.
Before Merge After 
{
  "foo" : "before",
  "bar" : "before",
  "baz" : "before"
}
          
{
  "__merge" : [
    [ "delete", "foo" ],
    [ "overwrite", "bar" ],
    [ "delete", "baz" ]
  ],
  "bar" : [ "after" ]
}
          
{
  "bar" : [ "after" ]
}