Overview

The JSON object provides methods for parsing JSON strings and converting values to JSON strings. These functions are essential for working with JSON data in expressions, particularly when you need to convert between string and object representations.

JSON.parse()

Description:

Parses a string as JSON and returns the resulting value or object.

This is similar to the JavaScript JSON.parse() method.

Syntax:

JSON.parse(text)

Parameters:

• text - A string containing valid JSON

Returns: The JavaScript value or object represented by the JSON string

Examples:

Parse null value:

JSON.parse("null")  // Returns: null

The string "null" is converted into the null value.

Parse array:

JSON.parse('[1,2,3.1,"one",true]')  // Returns: [1, 2, 3.1, "one", true]

The JSON string is converted into an array.

Parse object:

JSON.parse('{"name":"John","age":30}')  // Returns: {name: "John", age: 30}

Parse from field:

JSON.parse($jsonString)

Where $jsonString contains a JSON-formatted string from the input document.

JSON.stringify()

Description:

Converts a JavaScript value or object to a JSON string.

This is similar to the JavaScript JSON.stringify() method.

Syntax:

JSON.stringify(value)

Parameters:

• value - The value to convert to a JSON string

Returns: A JSON string representing the given value

Examples:

Stringify null value:

JSON.stringify(null)  // Returns: "null"

The null value is converted into the string "null".

Stringify date:

JSON.stringify(Date.now())  // Returns: "2017-03-22T17:58:03.485Z"

The Date value is converted into an ISO 8601 date string.

Stringify array:

JSON.stringify($array)  // Where $array contains [1, 2, 3.1, "one", true]
// Returns: "[1,2,3.1,\"one\",true]"

The array value is converted into a JSON string.

Stringify object:

JSON.stringify({name: "John", age: 30})  // Returns: "{\"name\":\"John\",\"age\":30}"

Stringify field value:

JSON.stringify($user)

Converts the $user object to a JSON string.

Common Use Cases

Parse JSON from API Response:

// When an API returns JSON as a string field
JSON.parse($response.data)

Convert Object to String for Storage:

// Store complex object as JSON string
JSON.stringify($order)

Parse Configuration String:

// Parse JSON configuration from pipeline parameter
JSON.parse(_configParam)

Format for Logging:

// Convert object to string for logging
"Processed order: " + JSON.stringify($order)

Deep Clone Object:

// Create a deep copy of an object
JSON.parse(JSON.stringify($originalObject))

Validate JSON String:

// Check if string is valid JSON (use in try/catch or validation)
JSON.parse($possiblyInvalidJson)

Best Practices

• Error Handling: Always validate that strings contain valid JSON before parsing. Invalid JSON will cause pipeline failures.
• Escape Characters: When working with JSON strings, ensure special characters are properly escaped (quotes, backslashes, etc.).
• Date Handling: Dates are serialized to ISO 8601 format strings. Parse them back with Date.parse() if needed.
• Undefined Values: JSON.stringify() omits object properties with undefined values. Use null explicitly if you need to preserve the property.
• Circular References: Objects with circular references cannot be stringified and will cause errors.
• Performance: For large objects, JSON parsing and stringifying can be expensive. Use sparingly in high-volume pipelines.

Comparison with Other Methods

Working with Nested JSON

Parse Nested Structure:

// Input: '{"user":{"name":"John","address":{"city":"Boston"}}}'
JSON.parse($jsonString).user.address.city  // Returns: "Boston"

Stringify with Nested Objects:

{
  "user": $userId,
  "metadata": JSON.stringify({
    "timestamp": Date.now(),
    "source": "pipeline"
  })
}

Extract and Parse Embedded JSON:

// When JSON is embedded in another JSON field
JSON.parse($record.embeddedData)