0
# Property Control
1

2
Core annotations for controlling property serialization, naming, and access patterns in Jackson data binding.
3

4
## Capabilities
5

6
### JsonProperty
7

8
Primary annotation for controlling property serialization and deserialization behavior.
9

10
```java { .api }
11
/**
12
 * Annotation for controlling property serialization and deserialization
13
 * @param value Property name in JSON (default: use field/method name)
14
 * @param namespace XML namespace for property (default: "")
15
 * @param required Whether property is required during deserialization (legacy)
16
 * @param isRequired Whether property is required (preferred over required)
17
 * @param index Ordering hint for property serialization (-1 = no ordering)
18
 * @param defaultValue Default value for property documentation
19
 * @param access Read/write access control for the property
20
 */
21
@JsonProperty(String value = "",
22
              String namespace = "",
23
              boolean required = false,
24
              OptBoolean isRequired = OptBoolean.DEFAULT,
25
              int index = JsonProperty.INDEX_UNKNOWN,
26
              String defaultValue = "",
27
              JsonProperty.Access access = JsonProperty.Access.AUTO)
28
public @interface JsonProperty {
29
    
30
    enum Access {
31
        /** Default access (read-write) */
32
        AUTO,
33
        
34
        /** Property only used during serialization (read-only) */
35
        READ_ONLY,
36
        
37
        /** Property only used during deserialization (write-only) */
38
        WRITE_ONLY,
39
        
40
        /** Property used for both serialization and deserialization */
41
        READ_WRITE
42
    }
43
    
44
    /** Default property name marker */
45
    String USE_DEFAULT_NAME = "";
46
    
47
    /** Unknown index marker */
48
    int INDEX_UNKNOWN = -1;
49
}
50
```
51

52
**Usage Examples:**
53

54
```java
55
public class User {
56
    // Basic property renaming
57
    @JsonProperty("firstName")
58
    private String name;
59
    
60
    // Required property
61
    @JsonProperty(value = "userId", required = true)
62
    private Long id;
63
    
64
    // Read-only property (only serialized)
65
    @JsonProperty(access = JsonProperty.Access.READ_ONLY)
66
    private String createdAt;
67
    
68
    // Write-only property (only deserialized)
69
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
70
    private String password;
71
    
72
    // Property ordering
73
    @JsonProperty(value = "email", index = 1)
74
    private String emailAddress;
75
}
76
```
77

78
### JsonAlias
79

80
Define alternative property names for deserialization flexibility.
81

82
```java { .api }
83
/**
84
 * Define alternative property names accepted during deserialization
85
 * @param value Array of alternative property names
86
 */
87
@JsonAlias(String[] value)
88
public @interface JsonAlias;
89
```
90

91
**Usage Examples:**
92

93
```java
94
public class Product {
95
    // Accept multiple property names during deserialization
96
    @JsonProperty("productName")
97
    @JsonAlias({"name", "title", "product_name"})
98
    private String name;
99
    
100
    // Handle different naming conventions
101
    @JsonProperty("price")
102
    @JsonAlias({"cost", "amount", "priceValue"})
103
    private BigDecimal price;
104
}
105

106
// This will deserialize all of these JSON variations:
107
// {"productName": "Laptop", "price": 999.99}
108
// {"name": "Laptop", "cost": 999.99}
109
// {"title": "Laptop", "amount": 999.99}
110
```
111

112
### JsonGetter
113

114
Mark a method as a getter for a logical property.
115

116
```java { .api }
117
/**
118
 * Mark method as getter for a logical property
119
 * @param value Property name (default: derive from method name)
120
 */
121
@JsonGetter(String value = "")
122
public @interface JsonGetter;
123
```
124

125
**Usage Examples:**
126

127
```java
128
public class Rectangle {
129
    private double width;
130
    private double height;
131
    
132
    @JsonGetter("area")
133
    public double calculateArea() {
134
        return width * height;
135
    }
136
    
137
    @JsonGetter  // Will use "perimeter" as property name
138
    public double getPerimeter() {
139
        return 2 * (width + height);
140
    }
141
}
142

143
// Serializes to: {"width": 5.0, "height": 3.0, "area": 15.0, "perimeter": 16.0}
144
```
145

146
### JsonSetter
147

148
Mark a method as a setter with null handling configuration.
149

150
```java { .api }
151
/**
152
 * Mark method as setter for a property with null handling
153
 * @param value Property name (default: derive from method name)
154
 * @param nulls How to handle null values
155
 * @param contentNulls How to handle null content (for collections/maps)
156
 */
157
@JsonSetter(String value = "",
158
            Nulls nulls = Nulls.DEFAULT,
159
            Nulls contentNulls = Nulls.DEFAULT)
160
public @interface JsonSetter;
161
```
162

163
**Usage Examples:**
164

165
```java
166
public class User {
167
    private String name;
168
    private List<String> tags;
169
    
170
    // Skip setting if null value received
171
    @JsonSetter(value = "userName", nulls = Nulls.SKIP)
172
    public void setName(String name) {
173
        this.name = name;
174
    }
175
    
176
    // Fail on null values
177
    @JsonSetter(nulls = Nulls.FAIL)
178
    public void setTags(List<String> tags) {
179
        this.tags = tags;
180
    }
181
    
182
    // Convert null content to empty list
183
    @JsonSetter(contentNulls = Nulls.AS_EMPTY)
184
    public void setCategories(List<String> categories) {
185
        this.categories = categories != null ? categories : new ArrayList<>();
186
    }
187
}
188
```
189

190
### JsonSetter.Value
191

192
Configuration class for programmatic JsonSetter configuration.
193

194
```java { .api }
195
/**
196
 * Value class for JsonSetter configuration
197
 */
198
public static class JsonSetter.Value implements JacksonAnnotationValue<JsonSetter> {
199
    public static final JsonSetter.Value EMPTY;
200
    
201
    public static JsonSetter.Value forValueNulls(Nulls nulls);
202
    public static JsonSetter.Value forContentNulls(Nulls nulls);
203
    public static JsonSetter.Value forValueNulls(Nulls valueNulls, Nulls contentNulls);
204
    
205
    public Nulls getValueNulls();
206
    public Nulls getContentNulls();
207
    public JsonSetter.Value withValueNulls(Nulls nulls);
208
    public JsonSetter.Value withContentNulls(Nulls nulls);
209
}
210
```
211

212
## Property Access Patterns
213

214
### Basic Property Mapping
215

216
```java
217
public class Person {
218
    @JsonProperty("full_name")
219
    private String name;
220
    
221
    @JsonProperty("birth_date")
222
    @JsonFormat(pattern = "yyyy-MM-dd")
223
    private LocalDate birthDate;
224
    
225
    // Constructor
226
    @JsonCreator
227
    public Person(@JsonProperty("full_name") String name,
228
                  @JsonProperty("birth_date") LocalDate birthDate) {
229
        this.name = name;
230
        this.birthDate = birthDate;
231
    }
232
}
233
```
234

235
### Advanced Access Control
236

237
```java
238
public class Account {
239
    @JsonProperty(value = "id", access = JsonProperty.Access.READ_ONLY)
240
    private Long accountId;
241
    
242
    @JsonProperty(access = JsonProperty.Access.WRITE_ONLY)
243
    private String password;
244
    
245
    private String email;
246
    
247
    @JsonGetter("email")
248
    public String getEmailAddress() {
249
        return email;
250
    }
251
    
252
    @JsonSetter("email")
253
    public void setEmailAddress(String email) {
254
        this.email = email.toLowerCase();
255
    }
256
}
257
```
258

259
### Multiple Name Support
260

261
```java
262
public class LegacyData {
263
    @JsonProperty("currentName")
264
    @JsonAlias({"oldName", "legacy_name", "previousName"})
265
    private String name;
266
    
267
    @JsonProperty("status")
268
    @JsonAlias({"state", "condition"})
269
    private String status;
270
}
271
```
272

273
### JsonPropertyDescription
274

275
Provide human-readable descriptions for properties, used in JSON schema generation.
276

277
```java { .api }
278
/**
279
 * Define human-readable description for a logical property
280
 * @param value Description text for the property
281
 */
282
@JsonPropertyDescription(String value = "")
283
public @interface JsonPropertyDescription;
284
```
285

286
**Usage Examples:**
287

288
```java
289
public class Product {
290
    @JsonProperty("id")
291
    @JsonPropertyDescription("Unique identifier for the product")
292
    private Long productId;
293
    
294
    @JsonProperty("name")
295
    @JsonPropertyDescription("Human-readable product name")
296
    private String displayName;
297
    
298
    @JsonProperty("price")
299
    @JsonPropertyDescription("Product price in USD, formatted as decimal")
300
    private BigDecimal price;
301
    
302
    @JsonPropertyDescription("Date when product was first created")
303
    private LocalDateTime createdAt;
304
}
305
```