0
# Inclusion and Exclusion
1

2
Control which properties are included or excluded during serialization and deserialization, with support for conditional inclusion and unknown property handling.
3

4
## Capabilities
5

6
### JsonIgnore
7

8
Exclude specific properties from serialization and deserialization.
9

10
```java { .api }
11
/**
12
 * Ignore property during serialization and deserialization
13
 * @param value Whether to ignore the property (default: true)
14
 */
15
@JsonIgnore(boolean value = true)
16
public @interface JsonIgnore;
17
```
18

19
**Usage Examples:**
20

21
```java
22
public class User {
23
    private String username;
24
    
25
    // Always ignored
26
    @JsonIgnore
27
    private String password;
28
    
29
    // Conditionally ignored (could be controlled programmatically)
30
    @JsonIgnore(false)
31
    private String email;
32
    
33
    private String internalId;
34
    
35
    @JsonIgnore
36
    public String getInternalId() {
37
        return internalId;
38
    }
39
}
40
```
41

42
### JsonIgnoreProperties
43

44
Ignore multiple properties by name or ignore unknown properties.
45

46
```java { .api }
47
/**
48
 * Ignore multiple properties by name or configure unknown property handling
49
 * @param value Array of property names to ignore
50
 * @param ignoreUnknown Whether to ignore unknown properties during deserialization
51
 * @param allowGetters Allow getter access for otherwise ignored properties
52
 * @param allowSetters Allow setter access for otherwise ignored properties
53
 */
54
@JsonIgnoreProperties(String[] value = {},
55
                      boolean ignoreUnknown = false,
56
                      boolean allowGetters = false,
57
                      boolean allowSetters = false)
58
public @interface JsonIgnoreProperties;
59
```
60

61
**Usage Examples:**
62

63
```java
64
// Ignore specific properties
65
@JsonIgnoreProperties({"password", "internalData", "tempField"})
66
public class Account {
67
    private String username;
68
    private String password;      // Ignored
69
    private String email;
70
    private Object internalData;  // Ignored
71
    private String tempField;     // Ignored
72
}
73

74
// Ignore unknown properties during deserialization
75
@JsonIgnoreProperties(ignoreUnknown = true)
76
public class ApiResponse {
77
    private String status;
78
    private String message;
79
    // Unknown properties in JSON will be ignored
80
}
81

82
// Allow getter but not setter for ignored properties
83
@JsonIgnoreProperties(value = {"readOnlyField"}, allowGetters = true)
84
public class Config {
85
    private String publicField;
86
    private String readOnlyField;  // Can be serialized but not deserialized
87
}
88
```
89

90
### JsonIgnoreType
91

92
Ignore all properties of a specific type.
93

94
```java { .api }
95
/**
96
 * Ignore all properties of annotated type
97
 * @param value Whether to ignore the type (default: true)
98
 */
99
@JsonIgnoreType(boolean value = true)
100
public @interface JsonIgnoreType;
101
```
102

103
**Usage Examples:**
104

105
```java
106
@JsonIgnoreType
107
public class InternalMetadata {
108
    private String internalId;
109
    private long timestamp;
110
}
111

112
public class Document {
113
    private String title;
114
    private String content;
115
    
116
    // This field will be ignored because InternalMetadata is annotated with @JsonIgnoreType
117
    private InternalMetadata metadata;
118
}
119
```
120

121
### JsonInclude
122

123
Control inclusion of properties based on their values.
124

125
```java { .api }
126
/**
127
 * Control inclusion of properties during serialization
128
 * @param value Primary inclusion criteria
129
 * @param content Inclusion criteria for collection/map/array contents
130
 * @param valueFilter Custom filter class for value inclusion decisions
131
 * @param contentFilter Custom filter class for content inclusion decisions
132
 */
133
@JsonInclude(JsonInclude.Include value = JsonInclude.Include.ALWAYS,
134
             JsonInclude.Include content = JsonInclude.Include.ALWAYS,
135
             Class<?> valueFilter = Void.class,
136
             Class<?> contentFilter = Void.class)
137
public @interface JsonInclude {
138
    
139
    enum Include {
140
        /** Always include property */
141
        ALWAYS,
142
        
143
        /** Include only if value is not null */
144
        NON_NULL,
145
        
146
        /** Include only if value is not null and not "absent" (for Optional, etc.) */
147
        NON_ABSENT,
148
        
149
        /** Include only if value is not empty (null, empty string, empty collection) */
150
        NON_EMPTY,
151
        
152
        /** Include only if value differs from default/initial value */
153
        NON_DEFAULT,
154
        
155
        /** Use custom filter for inclusion decision */
156
        CUSTOM,
157
        
158
        /** Use default inclusion settings */
159
        USE_DEFAULTS
160
    }
161
}
162
```
163

164
**Usage Examples:**
165

166
```java
167
public class Product {
168
    private String name;
169
    
170
    // Only include if not null
171
    @JsonInclude(JsonInclude.Include.NON_NULL)
172
    private String description;
173
    
174
    // Only include if not empty
175
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
176
    private List<String> tags;
177
    
178
    // Only include if different from default value
179
    @JsonInclude(JsonInclude.Include.NON_DEFAULT)
180
    private boolean active = true;
181
    
182
    // Only include non-null values in the map
183
    @JsonInclude(content = JsonInclude.Include.NON_NULL)
184
    private Map<String, String> attributes;
185
}
186
```
187

188
### JsonIncludeProperties
189

190
Include only specified properties (whitelist approach).
191

192
```java { .api }
193
/**
194
 * Include only specified properties (whitelist approach)
195
 * @param value Array of property names to include
196
 */
197
@JsonIncludeProperties(String[] value)
198
public @interface JsonIncludeProperties;
199
```
200

201
**Usage Examples:**
202

203
```java
204
@JsonIncludeProperties({"id", "name", "email"})
205
public class UserSummary {
206
    private Long id;
207
    private String name;
208
    private String email;
209
    private String password;      // Will be excluded
210
    private String internalData;  // Will be excluded
211
    private List<String> roles;   // Will be excluded
212
    
213
    // Only id, name, and email will be serialized
214
}
215

216
// Can also be used on individual properties
217
public class Response {
218
    @JsonIncludeProperties({"status", "message"})
219
    private ApiResult result;  // Only status and message from ApiResult will be included
220
}
221
```
222

223
### JsonInclude.Value and JsonIgnoreProperties.Value
224

225
Configuration classes for programmatic inclusion/exclusion control.
226

227
```java { .api }
228
/**
229
 * Value class for JsonInclude configuration
230
 */
231
public static class JsonInclude.Value implements JacksonAnnotationValue<JsonInclude> {
232
    public static final JsonInclude.Value EMPTY;
233
    
234
    public static JsonInclude.Value construct(JsonInclude.Include valueInclusion,
235
                                              JsonInclude.Include contentInclusion);
236
    
237
    public JsonInclude.Include getValueInclusion();
238
    public JsonInclude.Include getContentInclusion();
239
    public Class<?> getValueFilter();
240
    public Class<?> getContentFilter();
241
    
242
    public JsonInclude.Value withValueInclusion(JsonInclude.Include incl);
243
    public JsonInclude.Value withContentInclusion(JsonInclude.Include incl);
244
}
245

246
/**
247
 * Value class for JsonIgnoreProperties configuration
248
 */
249
public static class JsonIgnoreProperties.Value implements JacksonAnnotationValue<JsonIgnoreProperties> {
250
    public static final JsonIgnoreProperties.Value EMPTY;
251
    
252
    public static JsonIgnoreProperties.Value forIgnoredProperties(String... propNames);
253
    public static JsonIgnoreProperties.Value forIgnoreUnknown(boolean ignoreUnknown);
254
    
255
    public Set<String> getIgnored();
256
    public boolean getIgnoreUnknown();
257
    public boolean getAllowGetters();
258
    public boolean getAllowSetters();
259
    
260
    public JsonIgnoreProperties.Value withIgnored(String... propNames);
261
    public JsonIgnoreProperties.Value withIgnoreUnknown(boolean ignoreUnknown);
262
}
263
```
264

265
## Common Patterns
266

267
### API Response Filtering
268

269
```java
270
@JsonIgnoreProperties(ignoreUnknown = true)
271
public class ApiResponse<T> {
272
    private String status;
273
    private String message;
274
    
275
    @JsonInclude(JsonInclude.Include.NON_NULL)
276
    private T data;
277
    
278
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
279
    private List<String> errors;
280
    
281
    @JsonIgnore
282
    private long processingTime;
283
}
284
```
285

286
### Conditional Serialization
287

288
```java
289
public class User {
290
    private String username;
291
    
292
    @JsonInclude(JsonInclude.Include.NON_NULL)
293
    private String email;
294
    
295
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
296
    private String firstName;
297
    
298
    @JsonInclude(JsonInclude.Include.NON_EMPTY)
299
    private String lastName;
300
    
301
    @JsonIgnore
302
    private String passwordHash;
303
    
304
    // Only include if user has admin role
305
    @JsonInclude(JsonInclude.Include.NON_NULL)
306
    private String adminNotes;
307
}
308
```
309

310
### Legacy Data Handling
311

312
```java
313
@JsonIgnoreProperties(ignoreUnknown = true)  // Handle extra fields in old data
314
public class LegacyRecord {
315
    private String id;
316
    private String name;
317
    
318
    @JsonInclude(JsonInclude.Include.NON_NULL)
319
    private String migratedField;  // Only present in new records
320
    
321
    @JsonIgnoreProperties({"deprecatedField1", "deprecatedField2"})
322
    private SubRecord details;
323
}
324
```