0
# JSON-Smart
1

2
JSON-Smart is a lightweight, high-performance JSON processing library for Java that provides fast parsing, serialization, and dynamic navigation of JSON data. It offers both strict RFC4627 compliance and permissive parsing modes, along with extensive customization options.
3

4
## Package Information
5

6
- **Package Name**: net.minidev:json-smart
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Version**: 2.6.0-SNAPSHOT  
10
- **Java Version**: 8+
11
- **Installation**: 
12
  ```xml
13
  <dependency>
14
    <groupId>net.minidev</groupId>
15
    <artifactId>json-smart</artifactId>
16
    <version>2.6.0-SNAPSHOT</version>
17
  </dependency>
18
  ```
19

20
## Core Imports
21

22
```java
23
import net.minidev.json.JSONValue;
24
import net.minidev.json.JSONObject;
25
import net.minidev.json.JSONArray;
26
import net.minidev.json.JSONNavi;
27
import net.minidev.json.parser.JSONParser;
28
import net.minidev.json.JSONStyle;
29
```
30

31
## Basic Usage
32

33
```java
34
import net.minidev.json.JSONValue;
35
import net.minidev.json.JSONObject;
36
import net.minidev.json.JSONArray;
37

38
// Parse JSON string to Object
39
Object obj = JSONValue.parse("{\"name\": \"John\", \"age\": 30}");
40

41
// Parse to specific type
42
JSONObject person = JSONValue.parse("{\"name\": \"John\", \"age\": 30}", JSONObject.class);
43

44
// Create JSON objects programmatically
45
JSONObject user = new JSONObject()
46
    .appendField("name", "Alice")
47
    .appendField("age", 25)
48
    .appendField("active", true);
49

50
// Create JSON arrays
51
JSONArray numbers = new JSONArray()
52
    .appendElement(1)
53
    .appendElement(2)
54
    .appendElement(3);
55

56
// Serialize to JSON
57
String json = JSONValue.toJSONString(user);
58
System.out.println(json); // {"name":"Alice","age":25,"active":true}
59

60
// Validate JSON
61
boolean isValid = JSONValue.isValidJson("{\"test\": true}"); // true
62
```
63

64
## Architecture
65

66
JSON-Smart uses a multi-layered architecture:
67

68
- **Entry Layer**: `JSONValue` provides static utility methods for common operations
69
- **Object Model**: `JSONObject` and `JSONArray` extend standard Java collections with JSON-specific functionality
70
- **Parser Layer**: `JSONParser` handles configurable parsing with multiple modes (permissive, strict, streaming)
71
- **Navigation Layer**: `JSONNavi` provides jQuery-like dynamic traversal and manipulation
72
- **Extension Layer**: `JsonReader`/`JsonWriter` framework enables custom serialization/deserialization
73
- **Configuration Layer**: `JSONStyle` and parser flags control output formatting and parsing behavior
74

75
## Capabilities
76

77
### Core JSON Operations
78

79
Essential JSON parsing, creation, and serialization functionality using JSONValue, JSONObject, and JSONArray.
80

81
```java { .api }
82
// JSONValue - Main entry point
83
public static Object parse(String s);
84
public static <T> T parse(String s, Class<T> mapTo);
85
public static String toJSONString(Object value);
86
public static boolean isValidJson(String s);
87

88
// JSONObject - Object manipulation
89
public JSONObject appendField(String fieldName, Object fieldValue);
90
public String getAsString(String key);
91
public Number getAsNumber(String key);
92
public void merge(Object o2);
93

94
// JSONArray - Array manipulation  
95
public JSONArray appendElement(Object element);
96
public void merge(Object o2);
97
```
98

99
[Core JSON Operations](./core-api.md)
100

101
### Dynamic JSON Navigation
102

103
jQuery-like API for traversing and manipulating JSON structures without predefined types.
104

105
```java { .api }
106
// JSONNavi factory methods
107
public static JSONNavi<JSONAwareEx> newInstance();
108
public static JSONNavi<JSONObject> newInstanceObject();
109
public static JSONNavi<JSONArray> newInstanceArray();
110

111
// Navigation methods
112
public JSONNavi<?> at(String key);
113
public JSONNavi<?> at(int index);
114
public JSONNavi<T> root();
115
public JSONNavi<?> up();
116

117
// Value access and mutation
118
public String asString();
119
public JSONNavi<T> set(String key, Object value);
120
public JSONNavi<T> add(Object... values);
121
```
122

123
[Dynamic JSON Navigation](./navigation.md)
124

125
### Advanced JSON Parsing
126

127
Configurable parsing with multiple modes, streaming support, and detailed error handling.
128

129
```java { .api }
130
// JSONParser configuration
131
public static final int MODE_PERMISSIVE = 1;
132
public static final int MODE_RFC4627 = 2;
133
public static final int ACCEPT_SIMPLE_QUOTE = 1;
134
public static final int ACCEPT_NAN = 4;
135
public static final int ACCEPT_INCOMPLETE = 8192;
136

137
// Parsing methods
138
public Object parse(String in) throws ParseException;
139
public <T> T parse(String in, JsonReaderI<T> mapper) throws ParseException;
140

141
// MultipleJsonParser for streaming
142
public Object parseNext() throws ParseException;
143
public boolean hasNext();
144
```
145

146
[Advanced JSON Parsing](./parsing.md)
147

148
### Custom Serialization Framework
149

150
Extensible framework for implementing custom JSON serialization and deserialization logic.
151

152
```java { .api }
153
// Registration methods
154
public static <T> void registerWriter(Class<?> cls, JsonWriterI<T> writer);
155
public static <T> void registerReader(Class<T> type, JsonReaderI<T> mapper);
156
public static <T> void remapField(Class<T> type, String jsonFieldName, String javaFieldName);
157

158
// Custom interfaces
159
public interface JsonWriterI<T> {
160
    <E extends T> void writeJSONString(E value, Appendable out, JSONStyle compression) throws IOException;
161
}
162

163
public abstract class JsonReaderI<T> {
164
    public abstract T convert(Object current);
165
    public void setValue(Object current, String key, Object value) throws ParseException, IOException;
166
}
167
```
168

169
[Custom Serialization Framework](./customization.md)
170

171
### Output Formatting and Configuration
172

173
Control JSON output formatting, compression levels, and parser behavior through comprehensive configuration options.
174

175
```java { .api }
176
// JSONStyle constants
177
public static final JSONStyle NO_COMPRESS;
178
public static final JSONStyle MAX_COMPRESS;
179
public static final JSONStyle LT_COMPRESS;
180

181
// Formatting flags
182
public static final int FLAG_PROTECT_KEYS = 1;
183
public static final int FLAG_PROTECT_VALUES = 4;
184
public static final int FLAG_IGNORE_NULL = 16;
185

186
// JSONStyle methods
187
public JSONStyle(int FLAG);
188
public boolean protectKeys();
189
public boolean ignoreNull();
190
```
191

192
[Output Formatting and Configuration](./configuration.md)
193

194
## Types
195

196
```java { .api }
197
// Core exception type
198
class ParseException extends Exception {
199
    public int getErrorType();
200
    public int getPosition();
201
    public Object getUnexpectedObject();
202
}
203

204
// JSON interfaces
205
interface JSONAware {
206
    String toJSONString();
207
}
208

209
interface JSONAwareEx extends JSONAware {
210
    String toJSONString(JSONStyle compression);
211
}
212

213
interface JSONStreamAware {
214
    void writeJSONString(Appendable out) throws IOException;
215
}
216

217
interface JSONStreamAwareEx extends JSONStreamAware {
218
    void writeJSONString(Appendable out, JSONStyle compression) throws IOException;
219
}
220

221
// Annotation
222
@interface JsonIgnore {
223
    boolean value() default true;
224
}
225
```