0
# JsonPath Matchers
1

2
Core Hamcrest matchers for JsonPath-based assertions, providing the primary API for validating JSON documents using path expressions. These matchers integrate JsonPath's powerful querying capabilities with Hamcrest's expressive assertion framework.
3

4
## Capabilities
5

6
### Path Existence Validation
7

8
Validates whether specified JsonPath expressions exist within JSON documents.
9

10
```java { .api }
11
/**
12
 * Validates that the JSON document contains the specified path
13
 * @param jsonPath JsonPath expression as string
14
 * @return Matcher that succeeds if path exists
15
 */
16
public static Matcher<? super Object> hasJsonPath(String jsonPath);
17

18
/**
19
 * Validates that the JSON document contains the specified path and the value matches the given matcher
20
 * @param jsonPath JsonPath expression as string
21
 * @param resultMatcher Hamcrest matcher to validate the path value
22
 * @return Matcher that succeeds if path exists and value matches
23
 */
24
public static <T> Matcher<? super Object> hasJsonPath(String jsonPath, Matcher<T> resultMatcher);
25

26
/**
27
 * Validates that the JSON document does NOT contain the specified path
28
 * @param jsonPath JsonPath expression as string
29
 * @return Matcher that succeeds if path does not exist
30
 */
31
public static Matcher<? super Object> hasNoJsonPath(String jsonPath);
32
```
33

34
**Usage Examples:**
35

36
```java
37
import static com.jayway.jsonpath.matchers.JsonPathMatchers.*;
38
import static org.hamcrest.Matchers.*;
39
import static org.junit.Assert.assertThat;
40

41
String json = "{\"user\":{\"name\":\"Alice\",\"age\":30},\"items\":[\"book\",\"pen\"]}";
42

43
// Basic existence checks
44
assertThat(json, hasJsonPath("$.user.name"));
45
assertThat(json, hasJsonPath("$.items[0]"));
46
assertThat(json, hasNoJsonPath("$.user.email"));
47

48
// Value validation
49
assertThat(json, hasJsonPath("$.user.name", equalTo("Alice")));
50
assertThat(json, hasJsonPath("$.user.age", equalTo(30)));
51
assertThat(json, hasJsonPath("$.items", hasSize(2)));
52
assertThat(json, hasJsonPath("$.items[*]", hasItem("book")));
53
```
54

55
### JSON Validity Checks
56

57
Validates that input data is valid JSON and optionally applies additional matchers to the parsed content.
58

59
```java { .api }
60
/**
61
 * Validates that the input is valid JSON (contains Map or List at root)
62
 * @return Matcher that succeeds for valid JSON documents
63
 */
64
public static Matcher<Object> isJson();
65

66
/**
67
 * Validates that the input is valid JSON and applies the given matcher to the ReadContext
68
 * @param matcher Matcher to apply to the parsed JSON ReadContext
69
 * @return Matcher that succeeds if JSON is valid and matcher succeeds
70
 */
71
public static Matcher<Object> isJson(Matcher<? super ReadContext> matcher);
72

73
/**
74
 * Type-specific JSON validation for String inputs
75
 * @param matcher Matcher to apply to the parsed JSON ReadContext
76
 * @return Matcher specific to String inputs
77
 */
78
public static Matcher<String> isJsonString(Matcher<? super ReadContext> matcher);
79

80
/**
81
 * Type-specific JSON validation for File inputs
82
 * @param matcher Matcher to apply to the parsed JSON ReadContext
83
 * @return Matcher specific to File inputs
84
 */
85
public static Matcher<File> isJsonFile(Matcher<? super ReadContext> matcher);
86
```
87

88
**Usage Examples:**
89

90
```java
91
String validJson = "{\"key\":\"value\"}";
92
String invalidJson = "{ invalid-json }";
93
File jsonFile = new File("data.json");
94

95
// Basic validity
96
assertThat(validJson, isJson());
97
assertThat(invalidJson, not(isJson()));
98

99
// Type-specific validation with additional checks
100
assertThat(validJson, isJsonString(withJsonPath("$.key")));
101
assertThat(jsonFile, isJsonFile(withJsonPath("$.users[*]", hasSize(greaterThan(0)))));
102

103
// Complex validation combining multiple conditions
104
assertThat(validJson, isJson(allOf(
105
    withJsonPath("$.key", equalTo("value")),
106
    withoutJsonPath("$.missing")
107
)));
108
```
109

110
### ReadContext Matchers for Path Evaluation
111

112
Low-level matchers that work directly with JsonPath's ReadContext, enabling complex matcher combinations and pre-compiled path support.
113

114
```java { .api }
115
/**
116
 * Creates matcher for ReadContext with specified path (with optional filters)
117
 * @param jsonPath JsonPath expression as string
118
 * @param filters Optional Predicate filters for path evaluation
119
 * @return Matcher for ReadContext that succeeds if path exists
120
 */
121
public static Matcher<? super ReadContext> withJsonPath(String jsonPath, Predicate... filters);
122

123
/**
124
 * Creates matcher for ReadContext with pre-compiled JsonPath
125
 * @param jsonPath Pre-compiled JsonPath instance
126
 * @return Matcher for ReadContext that succeeds if path exists
127
 */
128
public static Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath);
129

130
/**
131
 * Creates matcher for ReadContext with path and value validation
132
 * @param jsonPath JsonPath expression as string
133
 * @param resultMatcher Matcher to validate the path value
134
 * @return Matcher that succeeds if path exists and value matches
135
 */
136
public static <T> Matcher<? super ReadContext> withJsonPath(String jsonPath, Matcher<T> resultMatcher);
137

138
/**
139
 * Creates matcher for ReadContext with pre-compiled path and value validation
140
 * @param jsonPath Pre-compiled JsonPath instance
141
 * @param resultMatcher Matcher to validate the path value
142
 * @return Matcher that succeeds if path exists and value matches
143
 */
144
public static <T> Matcher<? super ReadContext> withJsonPath(JsonPath jsonPath, Matcher<T> resultMatcher);
145

146
/**
147
 * Creates matcher for ReadContext that succeeds when path does NOT exist
148
 * @param jsonPath JsonPath expression as string
149
 * @param filters Optional Predicate filters for path evaluation
150
 * @return Matcher that succeeds if path does not exist
151
 */
152
public static Matcher<? super ReadContext> withoutJsonPath(String jsonPath, Predicate... filters);
153

154
/**
155
 * Creates matcher for ReadContext that succeeds when pre-compiled path does NOT exist
156
 * @param jsonPath Pre-compiled JsonPath instance
157
 * @return Matcher that succeeds if path does not exist
158
 */
159
public static Matcher<? super ReadContext> withoutJsonPath(JsonPath jsonPath);
160
```
161

162
**Usage Examples:**
163

164
```java
165
import com.jayway.jsonpath.JsonPath;
166
import com.jayway.jsonpath.Predicate;
167
import static com.jayway.jsonpath.Criteria.where;
168
import static com.jayway.jsonpath.Filter.filter;
169

170
String json = "{\"store\":{\"book\":[{\"category\":\"fiction\",\"price\":10.99},{\"category\":\"reference\",\"price\":8.95}]}}";
171

172
// Pre-compiled JsonPath for reuse
173
JsonPath expensiveBooks = JsonPath.compile("$.store.book[?(@.price > 10)]");
174
assertThat(json, isJson(withJsonPath(expensiveBooks, hasSize(1))));
175

176
// Complex filtering with predicates
177
Predicate cheapFictionFilter = filter(
178
    where("category").is("fiction").and("price").lte(10D));
179
JsonPath cheapFiction = JsonPath.compile("$.store.book[?]", cheapFictionFilter);
180
assertThat(json, isJson(withJsonPath(cheapFiction, hasSize(0))));
181

182
// Combining multiple ReadContext matchers
183
assertThat(json, isJson(allOf(
184
    withJsonPath("$.store.book", hasSize(2)),
185
    withJsonPath("$.store.book[0].category", equalTo("fiction")),
186
    withoutJsonPath("$.store.magazine")
187
)));
188
```
189

190
## Key Features
191

192
### Indefinite Paths and Empty Results
193

194
When using indefinite path expressions (wildcards, array slices), results yield collections that may be empty:
195

196
```java
197
String json = "{\"items\":[]}";
198

199
// Both assertions succeed - empty array is valid path result
200
assertThat(json, hasJsonPath("$.items[*]"));
201
assertThat(json, hasJsonPath("$.items[*].name"));
202

203
// Explicitly check for non-empty results when needed
204
assertThat(json, hasJsonPath("$.items[*]", hasSize(greaterThan(0))));
205
```
206

207
### Null Value Handling
208

209
Null is a valid JSON value and paths containing null are considered valid:
210

211
```java
212
String json = "{\"value\":null,\"missing\":undefined}";
213

214
// All succeed - null is a valid path value
215
assertThat(json, hasJsonPath("$.value"));
216
assertThat(json, hasJsonPath("$.value", nullValue()));
217
assertThat(json, isJson(withJsonPath("$.value", nullValue())));
218

219
// These fail - path doesn't exist
220
assertThat(json, not(hasJsonPath("$.missing")));
221
assertThat(json, not(isJson(withJsonPath("$.missing"))));
222
```
223

224
### Configuration Integration
225

226
JsonPath evaluation depends on the current JsonPath configuration:
227

228
```java
229
import com.jayway.jsonpath.Configuration;
230

231
// Configure JsonPath behavior globally
232
Configuration.setDefaults(customConfiguration);
233

234
// Matchers will use the configured settings for parsing and evaluation
235
assertThat(json, hasJsonPath("$.path", equalTo(expectedValue)));
236
```