0
# Jackson Annotations
1

2
Jackson Annotations is a zero-dependency library providing core annotations for Jackson data binding. It enables developers to control JSON serialization and deserialization behavior through annotations, supporting property renaming, type information handling, object creation patterns, and fine-grained control over the serialization process.
3

4
## Package Information
5

6
- **Package Name**: jackson-annotations
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: 
10
  ```xml
11
  <dependency>
12
    <groupId>com.fasterxml.jackson.core</groupId>
13
    <artifactId>jackson-annotations</artifactId>
14
    <version>2.19.0</version>
15
  </dependency>
16
  ```
17

18
## Core Imports
19

20
```java
21
import com.fasterxml.jackson.annotation.*;
22
```
23

24
Specific imports:
25
```java
26
import com.fasterxml.jackson.annotation.JsonProperty;
27
import com.fasterxml.jackson.annotation.JsonIgnore;
28
import com.fasterxml.jackson.annotation.JsonCreator;
29
import com.fasterxml.jackson.annotation.JsonTypeInfo;
30
```
31

32
## Basic Usage
33

34
```java
35
import com.fasterxml.jackson.annotation.*;
36

37
public class Person {
38
    @JsonProperty("firstName")
39
    private String name;
40
    
41
    @JsonIgnore
42
    private String password;
43
    
44
    @JsonProperty(required = true)
45
    private int age;
46
    
47
    @JsonCreator
48
    public Person(@JsonProperty("firstName") String name, 
49
                  @JsonProperty("age") int age) {
50
        this.name = name;
51
        this.age = age;
52
    }
53
    
54
    // getters and setters
55
}
56
```
57

58
## Architecture
59

60
Jackson Annotations follows a declarative annotation-based approach with several key components:
61

62
- **Property Annotations**: Control individual property serialization (`@JsonProperty`, `@JsonIgnore`, `@JsonAlias`)
63
- **Structure Annotations**: Modify object structure (`@JsonUnwrapped`, `@JsonValue`, `@JsonRawValue`)
64
- **Type System**: Handle polymorphic types (`@JsonTypeInfo`, `@JsonSubTypes`, `@JsonTypeName`)
65
- **Object Creation**: Control deserialization (`@JsonCreator`, `@JacksonInject`)
66
- **Meta-Annotations**: Framework integration (`@JacksonAnnotation`, `@JacksonAnnotationsInside`)
67
- **Value Classes**: Programmatic configuration via `JacksonAnnotationValue` implementations
68

69
## Capabilities
70

71
### Property Control
72

73
Annotations for controlling basic property serialization, naming, and access patterns. Essential for mapping Java field names to JSON properties and controlling visibility.
74

75
```java { .api }
76
@JsonProperty(String value = JsonProperty.USE_DEFAULT_NAME,
77
              String namespace = "",
78
              boolean required = false,
79
              OptBoolean isRequired = OptBoolean.DEFAULT, 
80
              int index = JsonProperty.INDEX_UNKNOWN, 
81
              String defaultValue = "", 
82
              JsonProperty.Access access = JsonProperty.Access.AUTO)
83
public @interface JsonProperty {
84
    enum Access { AUTO, READ_ONLY, WRITE_ONLY, READ_WRITE }
85
    
86
    String USE_DEFAULT_NAME = "";
87
    int INDEX_UNKNOWN = -1;
88
}
89

90
@JsonAlias(String[] value = {})
91
public @interface JsonAlias;
92

93
@JsonGetter(String value = "")
94
public @interface JsonGetter;
95

96
@JsonSetter(String value = "", Nulls nulls = Nulls.DEFAULT, 
97
            Nulls contentNulls = Nulls.DEFAULT)
98
public @interface JsonSetter;
99

100
@JsonPropertyDescription(String value = "")
101
public @interface JsonPropertyDescription;
102
```
103

104
[Property Control](./property-control.md)
105

106
### Inclusion and Exclusion
107

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

110
```java { .api }
111
@JsonIgnore(boolean value = true)
112
public @interface JsonIgnore;
113

114
@JsonIgnoreProperties(String[] value = {}, boolean ignoreUnknown = false,
115
                      boolean allowGetters = false, boolean allowSetters = false)
116
public @interface JsonIgnoreProperties;
117

118
@JsonInclude(JsonInclude.Include value = JsonInclude.Include.ALWAYS,
119
             JsonInclude.Include content = JsonInclude.Include.ALWAYS,
120
             Class<?> valueFilter = Void.class,
121
             Class<?> contentFilter = Void.class)
122
public @interface JsonInclude {
123
    enum Include { ALWAYS, NON_NULL, NON_ABSENT, NON_EMPTY, NON_DEFAULT, CUSTOM, USE_DEFAULTS }
124
}
125
```
126

127
[Inclusion and Exclusion](./inclusion-exclusion.md)
128

129
### Object Structure
130

131
Annotations that modify how objects are structured in JSON, including unwrapping nested objects and controlling value representation.
132

133
```java { .api }
134
@JsonUnwrapped(boolean enabled = true, String prefix = "", String suffix = "")
135
public @interface JsonUnwrapped;
136

137
@JsonValue(boolean value = true)
138
public @interface JsonValue;
139

140
@JsonRawValue(boolean value = true)
141
public @interface JsonRawValue;
142
```
143

144
[Object Structure](./object-structure.md)
145

146
### Object Creation and Injection
147

148
Control how objects are created during deserialization, including constructor/factory method selection and dependency injection.
149

150
```java { .api }
151
@JsonCreator(JsonCreator.Mode mode = JsonCreator.Mode.DEFAULT)
152
public @interface JsonCreator {
153
    enum Mode { DEFAULT, DELEGATING, PROPERTIES, DISABLED }
154
}
155

156
@JacksonInject(String value = "", OptBoolean useInput = OptBoolean.DEFAULT)
157
public @interface JacksonInject;
158
```
159

160
[Object Creation](./object-creation.md)
161

162
### Polymorphic Type Handling
163

164
Comprehensive support for handling polymorphic types with type information inclusion and subtype registration.
165

166
```java { .api }
167
@JsonTypeInfo(use = JsonTypeInfo.Id.NONE, include = JsonTypeInfo.As.PROPERTY,
168
              property = "", Class<?> defaultImpl = JsonTypeInfo.class,
169
              boolean visible = false,
170
              OptBoolean requireTypeIdForSubtypes = OptBoolean.DEFAULT)
171
public @interface JsonTypeInfo {
172
    enum Id { NONE, CLASS, MINIMAL_CLASS, NAME, SIMPLE_NAME, DEDUCTION, CUSTOM }
173
    enum As { PROPERTY, WRAPPER_OBJECT, WRAPPER_ARRAY, EXTERNAL_PROPERTY, EXISTING_PROPERTY }
174
}
175

176
@JsonSubTypes(JsonSubTypes.Type[] value, boolean failOnRepeatedNames = false)
177
public @interface JsonSubTypes {
178
    @interface Type {
179
        Class<?> value();
180
        String name() default "";
181
        String[] names() default {};
182
    }
183
}
184
```
185

186
[Polymorphic Types](./polymorphic-types.md)
187

188
### Object Identity and References
189

190
Handle circular references and object identity with configurable ID generation and reference management.
191

192
```java { .api }
193
@JsonIdentityInfo(String property = "@id",
194
                  Class<? extends ObjectIdGenerator<?>> generator,
195
                  Class<? extends ObjectIdResolver> resolver = SimpleObjectIdResolver.class,
196
                  Class<?> scope = Object.class)
197
public @interface JsonIdentityInfo;
198

199
@JsonManagedReference(String value = "defaultReference")
200
public @interface JsonManagedReference;
201

202
@JsonBackReference(String value = "defaultReference")
203
public @interface JsonBackReference;
204
```
205

206
[Object Identity](./object-identity.md)
207

208
### Formatting and Serialization Control
209

210
Control serialization format for dates, numbers, and other values with comprehensive formatting options.
211

212
```java { .api }
213
@JsonFormat(String pattern = "", JsonFormat.Shape shape = JsonFormat.Shape.ANY,
214
            String locale = JsonFormat.DEFAULT_LOCALE,
215
            String timezone = JsonFormat.DEFAULT_TIMEZONE,
216
            OptBoolean lenient = OptBoolean.DEFAULT,
217
            JsonFormat.Feature[] with = {},
218
            JsonFormat.Feature[] without = {})
219
public @interface JsonFormat {
220
    enum Shape { ANY, NATURAL, SCALAR, ARRAY, OBJECT, NUMBER, NUMBER_FLOAT, 
221
                 NUMBER_INT, STRING, BOOLEAN, BINARY }
222
}
223

224
@JsonEnumDefaultValue
225
public @interface JsonEnumDefaultValue;
226
```
227

228
[Formatting](./formatting.md)
229

230
### Configuration and Meta-Annotations
231

232
Auto-detection configuration, filtering, and meta-annotation support for creating custom annotation combinations.
233

234
```java { .api }
235
@JsonAutoDetect(JsonAutoDetect.Visibility getterVisibility = JsonAutoDetect.Visibility.DEFAULT,
236
                JsonAutoDetect.Visibility isGetterVisibility = JsonAutoDetect.Visibility.DEFAULT,
237
                JsonAutoDetect.Visibility setterVisibility = JsonAutoDetect.Visibility.DEFAULT,
238
                JsonAutoDetect.Visibility creatorVisibility = JsonAutoDetect.Visibility.DEFAULT,
239
                JsonAutoDetect.Visibility fieldVisibility = JsonAutoDetect.Visibility.DEFAULT)
240
public @interface JsonAutoDetect {
241
    enum Visibility { ANY, NON_PRIVATE, PROTECTED_AND_PUBLIC, PUBLIC_ONLY, NONE, DEFAULT }
242
}
243

244
@JsonClassDescription(String value = "")
245
public @interface JsonClassDescription;
246
```
247

248
[Configuration](./configuration.md)
249

250
## Supporting Types
251

252
Core enums and utility classes used throughout the annotation system:
253

254
```java { .api }
255
public enum OptBoolean {
256
    TRUE, FALSE, DEFAULT;
257
    
258
    public boolean asBoolean();
259
    public boolean asPrimitive();
260
    public static OptBoolean fromBoolean(Boolean b);
261
}
262

263
public enum Nulls {
264
    SET, SKIP, FAIL, AS_EMPTY, DEFAULT
265
}
266

267
public enum PropertyAccessor {
268
    GETTER, SETTER, CREATOR, FIELD, IS_GETTER, NONE, ALL;
269
    
270
    public boolean creatorEnabled();
271
    public boolean getterEnabled();
272
    public boolean isGetterEnabled();
273
    public boolean setterEnabled();
274
    public boolean fieldEnabled();
275
}
276

277
// JsonFormat constants
278
public static final String DEFAULT_LOCALE = "##default";
279
public static final String DEFAULT_TIMEZONE = "##default";
280
```