0
# Built-in Constraints
1
2
Comprehensive set of pre-defined constraint annotations for common validation scenarios including null checks, size validation, numeric ranges, date/time validation, and format validation.
3
4
## Capabilities
5
6
### Null Value Constraints
7
8
Constraints for validating null and non-null values.
9
10
```java { .api }
11
/**
12
* The annotated element must not be null
13
* Accepts any type
14
*/
15
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
16
@Retention(RUNTIME)
17
@Constraint(validatedBy = {})
18
@interface NotNull {
19
String message() default "{jakarta.validation.constraints.NotNull.message}";
20
Class<?>[] groups() default {};
21
Class<? extends Payload>[] payload() default {};
22
23
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
24
@Retention(RUNTIME)
25
@interface List {
26
NotNull[] value();
27
}
28
}
29
30
/**
31
* The annotated element must be null
32
* Accepts any type
33
*/
34
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
35
@Retention(RUNTIME)
36
@Constraint(validatedBy = {})
37
@interface Null {
38
String message() default "{jakarta.validation.constraints.Null.message}";
39
Class<?>[] groups() default {};
40
Class<? extends Payload>[] payload() default {};
41
42
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
43
@Retention(RUNTIME)
44
@interface List {
45
Null[] value();
46
}
47
}
48
```
49
50
**Usage Examples:**
51
52
```java
53
class User {
54
@NotNull
55
private String username; // Cannot be null
56
57
@Null
58
private String reserved; // Must be null
59
}
60
```
61
62
### String and Collection Constraints
63
64
Constraints for validating strings, collections, arrays, and maps.
65
66
```java { .api }
67
/**
68
* The annotated element must not be null and must contain at least one non-whitespace character
69
* Supported types: CharSequence
70
*/
71
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
72
@Retention(RUNTIME)
73
@Constraint(validatedBy = {})
74
@interface NotBlank {
75
String message() default "{jakarta.validation.constraints.NotBlank.message}";
76
Class<?>[] groups() default {};
77
Class<? extends Payload>[] payload() default {};
78
79
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
80
@Retention(RUNTIME)
81
@interface List {
82
NotBlank[] value();
83
}
84
}
85
86
/**
87
* The annotated element must not be null and not empty
88
* Supported types: CharSequence, Collection, Map, Array
89
*/
90
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
91
@Retention(RUNTIME)
92
@Constraint(validatedBy = {})
93
@interface NotEmpty {
94
String message() default "{jakarta.validation.constraints.NotEmpty.message}";
95
Class<?>[] groups() default {};
96
Class<? extends Payload>[] payload() default {};
97
98
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
99
@Retention(RUNTIME)
100
@interface List {
101
NotEmpty[] value();
102
}
103
}
104
105
/**
106
* The annotated element size must be between the specified boundaries (inclusive)
107
* Supported types: CharSequence, Collection, Map, Array
108
*/
109
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
110
@Retention(RUNTIME)
111
@Constraint(validatedBy = {})
112
@interface Size {
113
String message() default "{jakarta.validation.constraints.Size.message}";
114
Class<?>[] groups() default {};
115
Class<? extends Payload>[] payload() default {};
116
117
/**
118
* Size must be higher or equal to
119
* @return minimum size (inclusive)
120
*/
121
int min() default 0;
122
123
/**
124
* Size must be lower or equal to
125
* @return maximum size (inclusive)
126
*/
127
int max() default Integer.MAX_VALUE;
128
129
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
130
@Retention(RUNTIME)
131
@interface List {
132
Size[] value();
133
}
134
}
135
```
136
137
**Usage Examples:**
138
139
```java
140
class ValidationExamples {
141
@NotBlank
142
private String username; // Not null, not empty, not just whitespace
143
144
@NotEmpty
145
private List<String> items; // Not null and not empty
146
147
@Size(min = 2, max = 50)
148
private String name; // Length between 2 and 50 characters
149
150
@Size(max = 10)
151
private List<Item> itemList; // At most 10 items
152
}
153
```
154
155
### Numeric Constraints
156
157
Constraints for validating numeric values and ranges.
158
159
```java { .api }
160
/**
161
* The annotated element must be greater than or equal to the specified minimum
162
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long and their wrappers
163
*/
164
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
165
@Retention(RUNTIME)
166
@Constraint(validatedBy = {})
167
@interface Min {
168
String message() default "{jakarta.validation.constraints.Min.message}";
169
Class<?>[] groups() default {};
170
Class<? extends Payload>[] payload() default {};
171
172
/**
173
* The minimum value (inclusive)
174
* @return minimum value
175
*/
176
long value();
177
178
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
179
@Retention(RUNTIME)
180
@interface List {
181
Min[] value();
182
}
183
}
184
185
/**
186
* The annotated element must be less than or equal to the specified maximum
187
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long and their wrappers
188
*/
189
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
190
@Retention(RUNTIME)
191
@Constraint(validatedBy = {})
192
@interface Max {
193
String message() default "{jakarta.validation.constraints.Max.message}";
194
Class<?>[] groups() default {};
195
Class<? extends Payload>[] payload() default {};
196
197
/**
198
* The maximum value (inclusive)
199
* @return maximum value
200
*/
201
long value();
202
203
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
204
@Retention(RUNTIME)
205
@interface List {
206
Max[] value();
207
}
208
}
209
210
/**
211
* The annotated element must be greater than or equal to the specified minimum (supports decimal precision)
212
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long and their wrappers
213
*/
214
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
215
@Retention(RUNTIME)
216
@Constraint(validatedBy = {})
217
@interface DecimalMin {
218
String message() default "{jakarta.validation.constraints.DecimalMin.message}";
219
Class<?>[] groups() default {};
220
Class<? extends Payload>[] payload() default {};
221
222
/**
223
* The string representation of the minimum value
224
* @return minimum value as string
225
*/
226
String value();
227
228
/**
229
* Whether the specified minimum is inclusive or exclusive
230
* @return true for inclusive, false for exclusive
231
*/
232
boolean inclusive() default true;
233
234
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
235
@Retention(RUNTIME)
236
@interface List {
237
DecimalMin[] value();
238
}
239
}
240
241
/**
242
* The annotated element must be less than or equal to the specified maximum (supports decimal precision)
243
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long and their wrappers
244
*/
245
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
246
@Retention(RUNTIME)
247
@Constraint(validatedBy = {})
248
@interface DecimalMax {
249
String message() default "{jakarta.validation.constraints.DecimalMax.message}";
250
Class<?>[] groups() default {};
251
Class<? extends Payload>[] payload() default {};
252
253
/**
254
* The string representation of the maximum value
255
* @return maximum value as string
256
*/
257
String value();
258
259
/**
260
* Whether the specified maximum is inclusive or exclusive
261
* @return true for inclusive, false for exclusive
262
*/
263
boolean inclusive() default true;
264
265
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
266
@Retention(RUNTIME)
267
@interface List {
268
DecimalMax[] value();
269
}
270
}
271
272
/**
273
* The annotated element must be a strictly positive number (greater than 0)
274
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long, float, double and their wrappers
275
*/
276
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
277
@Retention(RUNTIME)
278
@Constraint(validatedBy = {})
279
@interface Positive {
280
String message() default "{jakarta.validation.constraints.Positive.message}";
281
Class<?>[] groups() default {};
282
Class<? extends Payload>[] payload() default {};
283
284
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
285
@Retention(RUNTIME)
286
@interface List {
287
Positive[] value();
288
}
289
}
290
291
/**
292
* The annotated element must be a positive number or zero
293
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long, float, double and their wrappers
294
*/
295
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
296
@Retention(RUNTIME)
297
@Constraint(validatedBy = {})
298
@interface PositiveOrZero {
299
String message() default "{jakarta.validation.constraints.PositiveOrZero.message}";
300
Class<?>[] groups() default {};
301
Class<? extends Payload>[] payload() default {};
302
303
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
304
@Retention(RUNTIME)
305
@interface List {
306
PositiveOrZero[] value();
307
}
308
}
309
310
/**
311
* The annotated element must be a strictly negative number (less than 0)
312
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long, float, double and their wrappers
313
*/
314
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
315
@Retention(RUNTIME)
316
@Constraint(validatedBy = {})
317
@interface Negative {
318
String message() default "{jakarta.validation.constraints.Negative.message}";
319
Class<?>[] groups() default {};
320
Class<? extends Payload>[] payload() default {};
321
322
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
323
@Retention(RUNTIME)
324
@interface List {
325
Negative[] value();
326
}
327
}
328
329
/**
330
* The annotated element must be a negative number or zero
331
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long, float, double and their wrappers
332
*/
333
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
334
@Retention(RUNTIME)
335
@Constraint(validatedBy = {})
336
@interface NegativeOrZero {
337
String message() default "{jakarta.validation.constraints.NegativeOrZero.message}";
338
Class<?>[] groups() default {};
339
Class<? extends Payload>[] payload() default {};
340
341
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
342
@Retention(RUNTIME)
343
@interface List {
344
NegativeOrZero[] value();
345
}
346
}
347
348
/**
349
* The annotated element must be a number within accepted range
350
* Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long and their wrappers
351
*/
352
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
353
@Retention(RUNTIME)
354
@Constraint(validatedBy = {})
355
@interface Digits {
356
String message() default "{jakarta.validation.constraints.Digits.message}";
357
Class<?>[] groups() default {};
358
Class<? extends Payload>[] payload() default {};
359
360
/**
361
* Maximum number of integral digits accepted for this number
362
* @return maximum integral digits
363
*/
364
int integer();
365
366
/**
367
* Maximum number of fractional digits accepted for this number
368
* @return maximum fractional digits
369
*/
370
int fraction();
371
372
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
373
@Retention(RUNTIME)
374
@interface List {
375
Digits[] value();
376
}
377
}
378
```
379
380
**Usage Examples:**
381
382
```java
383
class Product {
384
@Min(1)
385
private int quantity; // At least 1
386
387
@Max(100)
388
private int maxUsers; // At most 100
389
390
@DecimalMin("0.01")
391
@DecimalMax("999999.99")
392
private BigDecimal price; // Between 0.01 and 999999.99
393
394
@Positive
395
private Double rating; // Must be > 0
396
397
@PositiveOrZero
398
private int score; // Must be >= 0
399
400
@Digits(integer = 6, fraction = 2)
401
private BigDecimal amount; // Max 6 digits before decimal, 2 after
402
}
403
```
404
405
### Boolean Constraints
406
407
Constraints for validating boolean values.
408
409
```java { .api }
410
/**
411
* The annotated element must be true
412
* Supported types: boolean, Boolean
413
*/
414
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
415
@Retention(RUNTIME)
416
@Constraint(validatedBy = {})
417
@interface AssertTrue {
418
String message() default "{jakarta.validation.constraints.AssertTrue.message}";
419
Class<?>[] groups() default {};
420
Class<? extends Payload>[] payload() default {};
421
422
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
423
@Retention(RUNTIME)
424
@interface List {
425
AssertTrue[] value();
426
}
427
}
428
429
/**
430
* The annotated element must be false
431
* Supported types: boolean, Boolean
432
*/
433
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
434
@Retention(RUNTIME)
435
@Constraint(validatedBy = {})
436
@interface AssertFalse {
437
String message() default "{jakarta.validation.constraints.AssertFalse.message}";
438
Class<?>[] groups() default {};
439
Class<? extends Payload>[] payload() default {};
440
441
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
442
@Retention(RUNTIME)
443
@interface List {
444
AssertFalse[] value();
445
}
446
}
447
```
448
449
### Date and Time Constraints
450
451
Constraints for validating temporal values.
452
453
```java { .api }
454
/**
455
* The annotated element must be a date in the past
456
* Supported types: Date, Calendar, Instant, LocalDate, LocalDateTime, LocalTime, MonthDay, OffsetDateTime, OffsetTime, Year, YearMonth, ZonedDateTime, HijrahDate, JapaneseDate, MinguoDate, ThaiBuddhistDate
457
*/
458
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
459
@Retention(RUNTIME)
460
@Constraint(validatedBy = {})
461
@interface Past {
462
String message() default "{jakarta.validation.constraints.Past.message}";
463
Class<?>[] groups() default {};
464
Class<? extends Payload>[] payload() default {};
465
466
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
467
@Retention(RUNTIME)
468
@interface List {
469
Past[] value();
470
}
471
}
472
473
/**
474
* The annotated element must be a date in the past or in the present
475
* Supported types: Date, Calendar, Instant, LocalDate, LocalDateTime, LocalTime, MonthDay, OffsetDateTime, OffsetTime, Year, YearMonth, ZonedDateTime, HijrahDate, JapaneseDate, MinguoDate, ThaiBuddhistDate
476
*/
477
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
478
@Retention(RUNTIME)
479
@Constraint(validatedBy = {})
480
@interface PastOrPresent {
481
String message() default "{jakarta.validation.constraints.PastOrPresent.message}";
482
Class<?>[] groups() default {};
483
Class<? extends Payload>[] payload() default {};
484
485
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
486
@Retention(RUNTIME)
487
@interface List {
488
PastOrPresent[] value();
489
}
490
}
491
492
/**
493
* The annotated element must be a date in the future
494
* Supported types: Date, Calendar, Instant, LocalDate, LocalDateTime, LocalTime, MonthDay, OffsetDateTime, OffsetTime, Year, YearMonth, ZonedDateTime, HijrahDate, JapaneseDate, MinguoDate, ThaiBuddhistDate
495
*/
496
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
497
@Retention(RUNTIME)
498
@Constraint(validatedBy = {})
499
@interface Future {
500
String message() default "{jakarta.validation.constraints.Future.message}";
501
Class<?>[] groups() default {};
502
Class<? extends Payload>[] payload() default {};
503
504
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
505
@Retention(RUNTIME)
506
@interface List {
507
Future[] value();
508
}
509
}
510
511
/**
512
* The annotated element must be a date in the future or in the present
513
* Supported types: Date, Calendar, Instant, LocalDate, LocalDateTime, LocalTime, MonthDay, OffsetDateTime, OffsetTime, Year, YearMonth, ZonedDateTime, HijrahDate, JapaneseDate, MinguoDate, ThaiBuddhistDate
514
*/
515
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
516
@Retention(RUNTIME)
517
@Constraint(validatedBy = {})
518
@interface FutureOrPresent {
519
String message() default "{jakarta.validation.constraints.FutureOrPresent.message}";
520
Class<?>[] groups() default {};
521
Class<? extends Payload>[] payload() default {};
522
523
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
524
@Retention(RUNTIME)
525
@interface List {
526
FutureOrPresent[] value();
527
}
528
}
529
```
530
531
**Usage Examples:**
532
533
```java
534
import java.time.LocalDate;
535
import java.time.LocalDateTime;
536
537
class Event {
538
@AssertTrue
539
private boolean isActive; // Must be true
540
541
@AssertFalse
542
private boolean isDeleted; // Must be false
543
544
@Past
545
private LocalDate createdDate; // Must be in the past
546
547
@Future
548
private LocalDateTime eventDate; // Must be in the future
549
550
@PastOrPresent
551
private LocalDate lastModified; // Past or present
552
}
553
```
554
555
### Format and Pattern Constraints
556
557
Constraints for validating string formats and patterns.
558
559
```java { .api }
560
/**
561
* The annotated CharSequence must match the specified regular expression
562
* Supported types: CharSequence
563
*/
564
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
565
@Retention(RUNTIME)
566
@Constraint(validatedBy = {})
567
@interface Pattern {
568
String message() default "{jakarta.validation.constraints.Pattern.message}";
569
Class<?>[] groups() default {};
570
Class<? extends Payload>[] payload() default {};
571
572
/**
573
* The regular expression to match
574
* @return regular expression
575
*/
576
String regexp();
577
578
/**
579
* Array of Flag enums defining regex behavior
580
* @return regex flags
581
*/
582
Flag[] flags() default {};
583
584
/**
585
* Possible flags for Pattern constraint
586
*/
587
enum Flag {
588
UNIX_LINES(Pattern.UNIX_LINES),
589
CASE_INSENSITIVE(Pattern.CASE_INSENSITIVE),
590
COMMENTS(Pattern.COMMENTS),
591
MULTILINE(Pattern.MULTILINE),
592
DOTALL(Pattern.DOTALL),
593
UNICODE_CASE(Pattern.UNICODE_CASE),
594
CANON_EQ(Pattern.CANON_EQ);
595
596
private final int value;
597
598
Flag(int value) {
599
this.value = value;
600
}
601
602
public int getValue() {
603
return value;
604
}
605
}
606
607
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
608
@Retention(RUNTIME)
609
@interface List {
610
Pattern[] value();
611
}
612
}
613
614
/**
615
* The annotated element must be a well-formed email address
616
* Supported types: CharSequence
617
*/
618
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
619
@Retention(RUNTIME)
620
@Constraint(validatedBy = {})
621
@interface Email {
622
String message() default "{jakarta.validation.constraints.Email.message}";
623
Class<?>[] groups() default {};
624
Class<? extends Payload>[] payload() default {};
625
626
/**
627
* Regular expression to match email format (optional override)
628
* @return email regex pattern
629
*/
630
String regexp() default ".*";
631
632
/**
633
* Array of Flag enums for regex behavior (optional)
634
* @return regex flags
635
*/
636
Pattern.Flag[] flags() default {};
637
638
@Target({METHOD, FIELD, ANNOTATION_TYPE, CONSTRUCTOR, PARAMETER, TYPE_USE})
639
@Retention(RUNTIME)
640
@interface List {
641
Email[] value();
642
}
643
}
644
```
645
646
**Usage Examples:**
647
648
```java
649
class UserData {
650
651
private String email; // Valid email format
652
653
@Pattern(regexp = "^[A-Za-z0-9]+$")
654
private String username; // Alphanumeric only
655
656
@Pattern(regexp = "\\d{3}-\\d{3}-\\d{4}")
657
private String phoneNumber; // Format: 123-456-7890
658
659
@Pattern(regexp = "^(?=.*[A-Z])(?=.*[a-z])(?=.*\\d).{8,}$",
660
flags = {Pattern.Flag.MULTILINE})
661
private String password; // Strong password pattern
662
}
663
```