0
# JsonPath
1

2
JsonPath is a Java DSL (Domain Specific Language) for reading JSON documents using JsonPath expressions, similar to how XPath is used for XML. It supports both dot-notation and bracket-notation for accessing JSON elements, offers comprehensive operators for deep scanning, wildcards, and filtering, and provides a fluent API for parsing and evaluating JsonPath expressions against JSON data structures.
3

4
## Package Information
5

6
- **Package Name**: json-path
7
- **Package Type**: maven
8
- **Group ID**: com.jayway.jsonpath
9
- **Language**: Java
10
- **Installation**: Add dependency to your Maven or Gradle build file
11

12
Maven:
13
```xml
14
<dependency>
15
    <groupId>com.jayway.jsonpath</groupId>
16
    <artifactId>json-path</artifactId>
17
    <version>2.9.0</version>
18
</dependency>
19
```
20

21
Gradle:
22
```groovy
23
implementation 'com.jayway.jsonpath:json-path:2.9.0'
24
```
25

26
## Core Imports
27

28
```java
29
import com.jayway.jsonpath.JsonPath;
30
import com.jayway.jsonpath.DocumentContext;
31
import com.jayway.jsonpath.Configuration;
32
import com.jayway.jsonpath.Option;
33
import com.jayway.jsonpath.Filter;
34
import com.jayway.jsonpath.Criteria;
35
import com.jayway.jsonpath.Predicate;
36
```
37

38
## Basic Usage
39

40
```java
41
import com.jayway.jsonpath.JsonPath;
42
import com.jayway.jsonpath.DocumentContext;
43
import java.util.List;
44

45
// Simple static read operations
46
String json = "{ \"store\": { \"book\": [{ \"title\": \"Book 1\", \"price\": 8.95 }, { \"title\": \"Book 2\", \"price\": 12.99 }] } }";
47

48
// Read single value
49
String title = JsonPath.read(json, "$.store.book[0].title");
50
// Result: "Book 1"
51

52
// Read multiple values
53
List<String> titles = JsonPath.read(json, "$.store.book[*].title");
54
// Result: ["Book 1", "Book 2"]
55

56
// Using DocumentContext for multiple operations
57
DocumentContext context = JsonPath.parse(json);
58
String firstTitle = context.read("$.store.book[0].title");
59
List<Double> prices = context.read("$.store.book[*].price");
60

61
// Compile path for reuse
62
JsonPath compiledPath = JsonPath.compile("$.store.book[*].price");
63
List<Double> prices2 = compiledPath.read(json);
64
```
65

66
## Architecture
67

68
JsonPath is built around several key components:
69

70
- **JsonPath Class**: Main entry point providing static methods and compiled path instances
71
- **Context System**: DocumentContext, ReadContext, and WriteContext for different operation types
72
- **Configuration System**: Flexible configuration with options, JSON providers, and mapping providers
73
- **Filtering System**: Advanced filtering capabilities with Filter, Predicate, and Criteria classes
74
- **SPI (Service Provider Interface)**: Pluggable architecture for JSON parsing and object mapping
75
- **Exception Hierarchy**: Comprehensive error handling for different failure scenarios
76

77
## Capabilities
78

79
### Core Path Operations
80

81
Primary JsonPath functionality for reading, writing, and manipulating JSON documents using path expressions.
82

83
```java { .api }
84
// Static read operations
85
public static <T> T read(Object json, String jsonPath, Predicate... filters);
86
public static <T> T read(String json, String jsonPath, Predicate... filters);
87
public static <T> T read(File jsonFile, String jsonPath, Predicate... filters) throws IOException;
88
public static <T> T read(InputStream jsonInputStream, String jsonPath, Predicate... filters) throws IOException;
89

90
// Compiled path operations
91
public static JsonPath compile(String jsonPath, Predicate... filters);
92
public <T> T read(Object jsonObject);
93
public <T> T read(String json);
94
```
95

96
[Core Operations](./core-operations.md)
97

98
### Document Context Operations
99

100
Comprehensive read and write operations on parsed JSON documents, providing both reading capabilities and document modification features.
101

102
```java { .api }
103
// Parse methods
104
public static DocumentContext parse(Object json);
105
public static DocumentContext parse(String json);
106
public static DocumentContext parse(File json) throws IOException;
107
public static DocumentContext parse(InputStream json);
108

109
// DocumentContext interface methods
110
public interface DocumentContext extends ReadContext, WriteContext {
111
}
112

113
// Core read/write operations
114
public <T> T read(String path, Predicate... filters);
115
public DocumentContext set(String path, Object newValue, Predicate... filters);
116
public DocumentContext delete(String path, Predicate... filters);
117
public DocumentContext add(String path, Object value, Predicate... filters);
118
public DocumentContext put(String path, String key, Object value, Predicate... filters);
119
```
120

121
[Document Context](./document-context.md)
122

123
### Configuration and Options
124

125
Configuration system providing control over JSON parsing, mapping, options, and evaluation behavior.
126

127
```java { .api }
128
public class Configuration {
129
    public static Configuration defaultConfiguration();
130
    public static ConfigurationBuilder builder();
131
    
132
    public Configuration jsonProvider(JsonProvider newJsonProvider);
133
    public Configuration mappingProvider(MappingProvider newMappingProvider);
134
    public Configuration addOptions(Option... options);
135
    public Configuration setOptions(Option... options);
136
    public boolean containsOption(Option option);
137
}
138

139
public enum Option {
140
    DEFAULT_PATH_LEAF_TO_NULL,
141
    ALWAYS_RETURN_LIST,
142
    AS_PATH_LIST,
143
    SUPPRESS_EXCEPTIONS,
144
    REQUIRE_PROPERTIES
145
}
146
```
147

148
[Configuration](./configuration.md)
149

150
### Filtering and Predicates
151

152
Advanced filtering capabilities for creating complex queries with predicates, criteria builders, and custom filters.
153

154
```java { .api }
155
// Filter creation
156
public static Filter filter(Predicate predicate);
157
public static Filter filter(Collection<Predicate> predicates);
158
public static Filter parse(String filter);
159

160
// Criteria builder
161
public static Criteria where(String key);
162
public Criteria and(String key);
163
public Criteria is(Object o);
164
public Criteria eq(Object o);
165
public Criteria ne(Object o);
166
public Criteria lt(Object o);
167
public Criteria in(Object... o);
168
public Criteria contains(Object o);
169
```
170

171
[Filtering](./filtering.md)
172

173
### Type Handling and Mapping
174

175
Type-safe operations and object mapping capabilities for converting JSON data to specific Java types.
176

177
```java { .api }
178
// Type reference for generic types
179
public abstract class TypeRef<T> implements Comparable<TypeRef<T>> {
180
    public Type getType();
181
}
182

183
// Reading with type mapping
184
public <T> T read(String path, Class<T> type, Predicate... filters);
185
public <T> T read(JsonPath path, Class<T> type);
186
public <T> T read(JsonPath path, TypeRef<T> typeRef);
187

188
// Mapping interface
189
public interface MapFunction {
190
    Object map(Object currentValue, Configuration configuration);
191
}
192
```
193

194
[Type Handling](./type-handling.md)
195

196
## Exception Types
197

198
```java { .api }
199
// Base exception
200
public class JsonPathException extends RuntimeException {
201
    public JsonPathException();
202
    public JsonPathException(String message);
203
    public JsonPathException(String message, Throwable cause);
204
}
205

206
// Specific exceptions
207
public class InvalidPathException extends JsonPathException;
208
public class PathNotFoundException extends InvalidPathException;
209
public class InvalidJsonException extends JsonPathException;
210
public class InvalidCriteriaException extends JsonPathException;
211
public class InvalidModificationException extends JsonPathException;
212
public class ValueCompareException extends JsonPathException;
213
```
214

215
## SPI Interfaces
216

217
```java { .api }
218
// JSON provider interface
219
public interface JsonProvider {
220
    // Parsing methods
221
    Object parse(String json) throws InvalidJsonException;
222
    default Object parse(byte[] json) throws InvalidJsonException;
223
    Object parse(InputStream jsonStream, String charset) throws InvalidJsonException;
224
    
225
    // Serialization
226
    String toJson(Object obj);
227
    
228
    // Object creation
229
    Object createArray();
230
    Object createMap();
231
    
232
    // Type checking
233
    boolean isArray(Object obj);
234
    boolean isMap(Object obj);
235
    
236
    // Collection operations  
237
    int length(Object obj);
238
    Iterable<?> toIterable(Object obj);
239
    
240
    // Property access
241
    Object getArrayIndex(Object obj, int idx);
242
    @Deprecated
243
    Object getArrayIndex(Object obj, int idx, boolean unwrap);
244
    Object getMapValue(Object obj, String key);
245
    Collection<String> getPropertyKeys(Object obj);
246
    
247
    // Property modification
248
    void setProperty(Object obj, Object key, Object value);
249
    void setArrayIndex(Object obj, int idx, Object value);
250
    void removeProperty(Object obj, Object key);
251
    
252
    // Utility methods
253
    Object unwrap(Object obj);
254
    
255
    // Constants
256
    static final Object UNDEFINED = new Object();
257
}
258

259
// Mapping provider interface
260
public interface MappingProvider {
261
    <T> T map(Object source, Class<T> targetType, Configuration configuration);
262
    <T> T map(Object source, TypeRef<T> targetType, Configuration configuration);
263
}
264
```