json » addOrReplace(json,jsonpath,input,var)

Description

This command adds or replaces a portion of a JSON document (denoted by json) with either another JSON document or array (denoted by input). One can use jsonpath to specify the position or node of the JSON document to be replaced or added. The final outcome (should still be JSON) would be saved to var.

Flexibility is built into this command so that one can use it to add new JSON fragment (document) or JSON array, append to existing JSON fragment (document) or array, or replacing existing JSON fragment (document) or array. A good understanding of how this command works would give one the power to automate JSON document manipulation efficiently.

Limitations

• At this time, this command does not support deletion of JSON elements.
• At this time, this command does not support value-matching or regex-based filtering such as country.state[name=California].city[name=REGEX:San.+].

Both limitations will be addressed in the future.

Rules

The determination of whether to add to or replace a portion of target JSON depends on a number of rules. Essentially it comes down to the following rule:

• If the last "node" of jsonpath points to a non-existing JSON node, then input will be added to target json.
• If jsonpath cannot resolve to a JSON node in json or a non-existing leaf node, then input will be ignored.
• If jsonpath points to an existing JSON node, then
  • If target JSON is an array (i.e. [...]), inputappended to the array.
  • If target JSON is a simple value (text, number, boolean), it will be replaced by input.
  • If target JSON node is a JSON document (i.e. {...}), input that is also JSON document will be merged to target JSON node. Other types of input will be ignored.

Let's further understand these rules with further explanations and examples below.

action	json	jsonpath (points to)	input	example
ADD	empty or {}	empty	document	json empty jsonpath empty input "color": "yellow" result { "color": "yellow" } json empty jsonpath empty input { "color": "yellow"} result { "color": "yellow" }
ADD	document	empty	document	json { "shape": "square" } jsonpath empty input "color": "yellow" result {"shape":"square", "color":"yellow"} json { "COLOR": "YELLOW" } jsonpath empty input {"color":"yellow"} result {"color":"yellow","COLOR":"YELLOW"}
REPLACE	document	empty	document	json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath empty input {"department":null} result {"department":null}
REPLACE	document	empty	null	json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath empty input null result null
ADD	document	node (existing)	document	json {"color":{"name":"YELLOW","hue":{"red":255}}} jsonpath color.hue input {"green":255,"blue":0} result {"color":{   "name":"YELLOW",   "hue":{"red":255,"green":255,"blue":0}} }
REPLACE	document	node (existing)	document (same name as existing node)	json {"color":{"brightness":0.254,"name":"YELLOW","hue":[255,0,0]}} jsonpath color input {"hue":[255,255,0]} result {"color":{   "brightness":0.254,   "name":"YELLOW",   "hue":[255,255,0]} }
ADD	document	array (existing)	document	json {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"} ]} jsonpath departments input {"group":"Support","employees":["Peter","Paul","Pippy"]} result {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"},   {"employees":["Peter","Paul","Pippy"],"group":"Support"} ]}
ADD	document	array (existing)	array	json {"color":{"brightness":0.254,"name":"YELLOW","hue":[255,0,0]}} jsonpath color.hue input [1,2,3] result {"color":{   "brightness":0.254,   "name":"YELLOW",   "hue":[255,0,0,1,2,3]} } json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath departments[1].employees input ["Peter","Paul","Pippy"] result {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo","Peter","Paul","Pippy"]} ]}
ADD	document	array (empty, existing)	document	json {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"},   {"favorites":[]} ]} jsonpath departments[2].favorites input {"color":"pink","numbers":[3,2,1.5]} result {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"},   {"favorites":[{"color":"pink","numbers":[3,2,1.5]}]} ]}
ADD	document	array index (existing)	simple value	json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath departments[1].employees[3] input 1353.234 result {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo",1353.234]} ]}
REPLACE	document	array index (existing)	document	json {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"},   {"favorites":[]} ]} jsonpath departments[2] input {"favorites":{"color":"black","numbers":[42,39,7.14]}} result {"departments":[   {"employees":["John","James","Jack"],"group":"Technology"},   {"employees":["Adam","Abbey","Apollo"],"group":"Accounting"},   {"favorites":{"color":"black","numbers":[42,39,7.14]}} ]}
REPLACE	document	array index (existing)	array	json {"color":{"brightness":0.254,"name":"YELLOW","hue":[255,0,0]}} jsonpath color.hue[1] input [255,0] result {"color":{   "brightness":0.254,   "name":"YELLOW",   "hue":[255,[255,0],0]} }
REPLACE	document	array index (existing)	document	json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath departments[0] input {"employees":null,"group":null} result {"departments":[   {"group":null,"employees":null},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]}
REPLACE	document	simple value (existing)	document	json {"color":"YELLOW"} jsonpath color input {"red":250,"green":250,"blue":230} result {"color":{"red":250,"green":250,"blue":230}}
ADD	array	empty	document	json [255,2,3] jsonpath empty input {"extra":[213,94]} result [255,2,3,{"extra":[213,94]}]
ADD	array	empty	array	json [255,2,3] jsonpath empty input [254,54] result [255,2,3,254,54]
ADD	array	array	list	json {"color":["YELLOW"]} jsonpath color input true,"chicken",59.2 result {"color":["YELLOW",true,"chicken",59.2]}
ADD	array	array index (non-existing)	list	json {"color":["YELLOW"]} jsonpath color[1] input true,"chicken",59.2 result {"color":["YELLOW",[true,"chicken",59.2]]}
ADD	array	array index (non-existing)	simple value	json {"color":["YELLOW"]} jsonpath color[1] input pink result {"color":["YELLOW","pink"]}
none	document	node (non-existing)	array	json {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]} jsonpath departments[1].years input [16,5,2.7] result {"departments":[   {"group":"Technology","employees":["John","James","Jack"]},   {"group":"Accounting","employees":["Adam","Abbey","Apollo"]} ]}
none	array	node (non-existing)	array	json [255,2,3] jsonpath a input [213,94] result [255,2,3]

Parameters

• json - the JSON content or JSON file to validate for correctness
• jsonpath - the jsonpath to reference a node or array of json
• input - the JSON to add or replace
• var - the variable to save the resultant JSON document.

Example

Script:

Output:

For more examples, see above.