Skip to content

writeJson

Signature

function writeJson(string calldata json, string calldata path) external;
 
function writeJson(string calldata json, string calldata path, string calldata valueKey) external;

Description

Writes a serialized JSON object to a file.

The argument json must be a JSON object in stringified form. For example:

{ "boolean": true, "number": 342, "object": { "title": "finally json serialization" } }

This is usually built through serializeJson.

The argument path is the path of the JSON file to write to.

If no valueKey is provided, then the JSON object will be written to a new file. If the file already exists, it will be overwritten.

If a valueKey is provided, then the file must already exist and be a valid JSON file. The object in that file will be updated by replacing the value at the JSON path valueKey with the JSON object json.

This is useful for replacing some values in a JSON file without having to first parse and then reserialize it. Note that if the specified key, or any of the intermediate ones in the JSON path, don't exist, they will be created.

Remember: The file path path needs to be in the allowed paths. Read more in File cheatcodes.

JSON Paths

Let's consider the following JSON object:

{
  "boolean": true,
  "number": 342,
  "obj1": {
    "aNumber": 123,
    "obj2": {
      "aNumber": 123,
      "obj3": {
        "veryDeep": 13371337
      }
    }
  }
}

Important: JSON paths must be properly formatted to work correctly:

  • Root object assumption: The root object is always assumed, so you should start paths with a dot (.) or dollar sign ($)
  • Dot notation: Use .boolean, .number, .obj1 to access root-level properties
  • Nested access: Use .obj1.aNumber or .obj1.obj2.aNumber to go deeper into the structure
  • Descendant search: Use ..keyName to search for a key anywhere in a subtree, like .obj1..veryDeep or just ..veryDeep

Common mistake: Using bare key names like "key.foo" will be silently converted to "$key.foo" by the JSONPath parser, which will fail because it looks for a root property named key.foo. Instead, use ".key.foo" or "$.key.foo".

Valid path examples:

  • .boolean - accesses the boolean property at root level
  • $.boolean - equivalent to above using explicit root notation
  • .obj1.aNumber - accesses nested property
  • .obj1..veryDeep - finds veryDeep anywhere within obj1
  • ..veryDeep - finds veryDeep anywhere in the document

See the examples to see this in action.

Examples

A simple example

string memory jsonObj = '{ "boolean": true, "number": 342, "myObject": { "title": "finally json serialization" } }';
vm.writeJson(jsonObj, "./output/example.json");
 
// replaces the value of `myObject` with a new object
string memory newJsonObj = '{ "aNumber": 123, "aString": "asd" }';
vm.writeJson(newJsonObj, "./output/example.json", ".myObject");
 
// replaces the value of `aString` in the new object
vm.writeJson("my new string", "./output/example.json", ".myObject.aString");
 
// Here's example.json:
//
// {
//   "boolean": true,
//   "number": 342,
//   "myObject": {
//     "aNumber": 123,
//     "aString": "my new string"
//   }
// }

A more complex example

string memory jsonObj = '{ "boolean": true, "number": 342, "obj1": { "foo": "bar" } }';
vm.writeJson(jsonObj, "./output/example2.json");
 
string memory jsonObj2 = '{ "aNumber": 123, "obj2": {} }';
vm.writeJson(jsonObj2, "./output/example2.json", ".obj1");
 
string memory jsonObj3 = '{ "aNumber": 123, "obj3": { "veryDeep": 3 } }';
vm.writeJson(jsonObj3, "./output/example2.json", ".obj1.obj2");
 
// Here's example2.json so far:
//
// {
//   "boolean": true,
//   "number": 342,
//   "obj1": {
//     "aNumber": 123,
//     "obj2": {
//       "aNumber": 123,
//       "obj3": {
//         "veryDeep": 3
//       }
//     }
//   }
// }
 
// Note that the JSON object is just the value 13371337 in this case.
vm.writeJson("13371337", "./output/example2.json", "..veryDeep");
 
// Here's the final example2.json:
//
// {
//   "boolean": true,
//   "number": 342,
//   "obj1": {
//     "aNumber": 123,
//     "obj2": {
//       "aNumber": 123,
//       "obj3": {
//         "veryDeep": 13371337
//       }
//     }
//   }
// }

SEE ALSO