JsonMatch

Testing JSON strings or object instances for matching against a condition expressed in a DSL (Domain Specific Language) similar to WHERE clauses in SQL. It is limited to operations on JSON native data types, i.e. String, Integer, Number, and Boolean (but not DateTime).

Usage

You have to use the matcher(expression: String) operation to retrieve an instance of Matcher (this operation may throw an exception of type “JsonMatch“, code “SYNTAX“, and message with details). Use the matcher instance to test as many JSON strings (matchesJson(string)) or Objects (matchesAny(object)) for matching your condition. The operation matchesAny() will implicitly call classToJSON() on the given object. The functionality is built for scenarios that evaluate more than one JSON against an expression. Since parsing the expression and building the Matcher’s internal data structures is costly, they won’t be removed automatically, therefore:

To illustrate what can be expressed and tested for, take this JSON snippet:

JSON Object

{
	"autoRetry": false,
	"autoRetryTime": "PT60S",
	"currentTask": {
		"begin": "2023-07-21T17:33:14.005054Z",
		"name": "wait_for_Godot",
		"stateName": "Waiting for wait_for_Godot"
	},
	"holdTime": "PT60S",
	"id": "000001277983434200003a8ce77fe700a8beba4d",
	"myBoolean": true,
	"myFloat": 3.0,
	"myInteger": 3,
	"myString": "three",
	"originalValues": {
		"aBoolean": true,
		"aFloat": 3.0,
		"aInt": 3,
		"aString": "three"
	},
	"stateId": 0
}

The following example expressions show the most important supported expression elements, are syntactically correct and matchesJson() will return true:

myBoolean = true AND (myFloat >= 3.0 OR myString IN ['three', 'four', 'five'])  -- AND, OR, and IN
autoRetryTime MATCH 'PT[0-9]{2}S' AND autoRetry = true                          -- MATCH allows for testing against regular expressions
currentTask.stateName NIN ['Error', 'Abort'] AND originalValues.aInt > 0        -- NIN (not IN) as opposed to IN, accessing nested attributes by dot notation
myBoolean == REF(originalValues.aBoolean)                                       -- comparing attribute values to other attribute values need the REF() operator to indicate the attribute to compare with

The railroad diagrams of the DSL:

Expression Syntax Diagram (show | hide)

Related Content