UTIL_JsonPath

Class · Group: Utilities

global inherited sharing class UTIL_JsonPath

Utility class to streamline parsing nested JSON data structures. Provides methods to navigate and extract data from JSON using dot notation paths, with support for type-safe value retrieval and existence checks. Adapted from open-force.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"account": {"name": "Acme", "active": true}}');
String name = json.get('account.name').getStringValue();
Boolean active = json.get('account.active').getBooleanValue();
Boolean exists = json.exists('account.name');

---

Methods

Method	Description
global Boolean exists(String path)	Checks if a path exists in the JSON data structure.
global UTIL_JsonPath findNode(String path)	Navigates to a subtree in the JSON data using a dot notation path.
global UTIL_JsonPath get(String path)	Retrieves a subtree in the JSON data using a dot notation path.
global Boolean getBooleanValue()	Converts the wrapped JSON data to a Boolean.
global Datetime getDatetimeValue()	Converts the wrapped JSON data to a Datetime, supporting ISO-8601 strings or timestamps (Long).
global Date getDateValue()	Converts the wrapped JSON data to a Date, supporting ISO-8601 strings or timestamps (Long).
global Decimal getDecimalValue()	Converts the wrapped JSON data to a Decimal.
global Id getIdValue()	Converts the wrapped JSON data to a Salesforce Id, validating the string format.
global Integer getIntegerValue()	Converts the wrapped JSON data to an Integer.
global String getStringValue()	Converts the wrapped JSON data to a String, excluding objects and arrays.
global Boolean isArray()	Checks if the wrapped JSON data is an array (List).
global Boolean isObject()	Checks if the wrapped JSON data is an object (Map).
global String toStringPretty()	Serializes the wrapped JSON data to a pretty-printed JSON string.

exists

global Boolean exists(String path)

Checks if a path exists in the JSON data structure.

Parameters

Parameter	Type	Description
path	String	The dot notation path to check.

Returns Boolean — True if the path exists, false otherwise.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"data": {"items": [{"id": 1}]}}');
Boolean existsFirst = json.exists('data.items[0]');
Boolean existsSecond = json.exists('data.items[1]');

findNode

global UTIL_JsonPath findNode(String path)

Navigates to a subtree in the JSON data using a dot notation path.

Parameters

Parameter	Type	Description
path	String	The dot notation path to the desired subtree.

Returns UTIL_JsonPath — A UTIL_JsonPath instance wrapping the targeted subtree, or null if the path does not exist.

Example

UTIL_JsonPath result = instance.findNode('value');

get

global UTIL_JsonPath get(String path)

Retrieves a subtree in the JSON data using a dot notation path.

Supports paths with array indices (e.g., data.items[1]) and object keys.

Parameters

Parameter	Type	Description
path	String	The dot notation path to the desired data.

Returns UTIL_JsonPath — A UTIL_JsonPath instance wrapping the targeted subtree.

Throws

Exception	Description
ListException	If an array index is out of bounds.
MissingKeyException	If a key in the path does not exist in the JSON object.
UTIL_Exceptions.IllegalStateException	If an array index is applied to a non-array node or a key is applied to a non-object node.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"data": {"items": [{"id": 1}, {"id": 2}]}}');
UTIL_JsonPath item = json.get('data.items[1]');
String id = item.getStringValue();

getBooleanValue

global Boolean getBooleanValue()

Converts the wrapped JSON data to a Boolean.

Returns Boolean — The value as a Boolean.

Throws

Exception	Description
TypeException	If the value is not a Boolean or convertible string.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"isActive": true}');
Boolean isActive = json.get('isActive').getBooleanValue();

getDatetimeValue

global Datetime getDatetimeValue()

Converts the wrapped JSON data to a Datetime, supporting ISO-8601 strings or timestamps (Long).

Returns Datetime — The value as a Datetime.

Throws

Exception	Description
TypeException	If the value is not a String or Long.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"timestamp": 1625097600000}');
Datetime dt = json.get('timestamp').getDatetimeValue();

getDateValue

global Date getDateValue()

Converts the wrapped JSON data to a Date, supporting ISO-8601 strings or timestamps (Long).

Returns Date — The value as a Date.

Throws

Exception	Description
TypeException	If the value is not a String or Long.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"date": "2021-07-01"}');
Date dt = json.get('date').getDateValue();

getDecimalValue

global Decimal getDecimalValue()

Converts the wrapped JSON data to a Decimal.

Returns Decimal — The value as a Decimal.

Throws

Exception	Description
TypeException	If the value is not a Decimal or convertible string.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"amount": "123.45"}');
Decimal amount = json.get('amount').getDecimalValue();

getIdValue

global Id getIdValue()

Converts the wrapped JSON data to a Salesforce Id, validating the string format.

Returns Id — The value as an Id.

Throws

Exception	Description
StringException	If the string is not a valid Salesforce Id.
TypeException	If the value is not a string.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"recordId": "001xx0000000000AAA"}');
Id recordId = json.get('recordId').getIdValue();

getIntegerValue

global Integer getIntegerValue()

Converts the wrapped JSON data to an Integer.

Returns Integer — The value as an Integer.

Throws

Exception	Description
TypeException	If the value is not an Integer, Decimal, or convertible string.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"count": "42"}');
Integer count = json.get('count').getIntegerValue();

getStringValue

global String getStringValue()

Converts the wrapped JSON data to a String, excluding objects and arrays.

Returns String — The value as a String.

Throws

Exception	Description
TypeException	If the value is a JSON object or array.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"name": "John"}');
String name = json.get('name').getStringValue();

isArray

global Boolean isArray() global Boolean isObject() global String toStringPretty()

Checks if the wrapped JSON data is an array (List ).

Returns Boolean — True if the value is a JSON array, false otherwise.

Example

UTIL_JsonPath json = new UTIL_JsonPath('[{"id": 1}]');
Boolean result = json.isArray();

isObject

global Boolean isObject()

Checks if the wrapped JSON data is an object (Map ).

Returns Boolean — True if the value is a JSON object, false otherwise.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"key": "value"}');
Boolean result = json.isObject();

toStringPretty

global String toStringPretty()

Serializes the wrapped JSON data to a pretty-printed JSON string.

Returns String — A formatted JSON string.

Example

UTIL_JsonPath json = new UTIL_JsonPath('{"key": "value"}');
String result = json.toStringPretty();

Constructors

Constructor	Description
global UTIL_JsonPath(String jsonData)	Constructs a UTIL_JsonPath instance from a serialized JSON string.

UTIL_JsonPath(String jsonData)

global UTIL_JsonPath(String jsonData)

Constructs a UTIL_JsonPath instance from a serialized JSON string.

Parameters

Parameter	Type	Description
jsonData	String	The JSON string to parse.

Example

UTIL_JsonPath instance = new UTIL_JsonPath('value');

Inner Classes

Class	Description
MissingKeyException	Custom exception thrown when a JSON path key cannot be resolved.

---