0
# Built-in Constraint Annotations
1

2
Hibernate Validator provides an extensive collection of constraint annotations beyond the standard Jakarta Validation constraints. These include string validators, financial validators, product identifiers, time constraints, script-based validation, and country-specific validators.
3

4
All constraints in this document are from the `org.hibernate.validator.constraints` package unless otherwise noted. All constraints support `null` values as valid (use `@NotNull` to disallow null).
5

6
## Capabilities
7

8
### String Length and Format Constraints
9

10
String length and Unicode normalization validators providing alternatives and extensions to standard `@Size` constraint.
11

12
```java { .api }
13
package org.hibernate.validator.constraints;
14

15
import jakarta.validation.Constraint;
16
import jakarta.validation.Payload;
17
import java.lang.annotation.*;
18

19
/**
20
 * Validates string length is between min and max (inclusive).
21
 * Hibernate-specific alternative to @Size for CharSequence.
22
 *
23
 * Supported types: CharSequence
24
 */
25
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
26
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
27
@Retention(RetentionPolicy.RUNTIME)
28
@Constraint(validatedBy = {})
29
@interface Length {
30
    /**
31
     * Minimum length (inclusive). Default: 0
32
     */
33
    int min() default 0;
34

35
    /**
36
     * Maximum length (inclusive). Default: Integer.MAX_VALUE
37
     */
38
    int max() default Integer.MAX_VALUE;
39

40
    String message() default "{org.hibernate.validator.constraints.Length.message}";
41
    Class<?>[] groups() default {};
42
    Class<? extends Payload>[] payload() default {};
43
}
44

45
/**
46
 * Validates code point length of character sequence with Unicode normalization support.
47
 * Code points are Unicode characters, where some characters may be composed of multiple
48
 * Java char values (e.g., emojis, surrogate pairs).
49
 *
50
 * Supported types: CharSequence
51
 * @since 6.0.3
52
 */
53
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
54
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
55
@Retention(RetentionPolicy.RUNTIME)
56
@Constraint(validatedBy = {})
57
@interface CodePointLength {
58
    /**
59
     * Minimum code point length (inclusive). Default: 0
60
     */
61
    int min() default 0;
62

63
    /**
64
     * Maximum code point length (inclusive). Default: Integer.MAX_VALUE
65
     */
66
    int max() default Integer.MAX_VALUE;
67

68
    /**
69
     * Unicode normalization strategy to apply before counting.
70
     * Default: NONE (no normalization)
71
     */
72
    NormalizationStrategy normalizationStrategy() default NormalizationStrategy.NONE;
73

74
    String message() default "{org.hibernate.validator.constraints.CodePointLength.message}";
75
    Class<?>[] groups() default {};
76
    Class<? extends Payload>[] payload() default {};
77

78
    /**
79
     * Unicode normalization strategies.
80
     */
81
    enum NormalizationStrategy {
82
        /** No normalization */
83
        NONE,
84
        /** Canonical Decomposition (NFD) */
85
        NFD,
86
        /** Canonical Decomposition followed by Canonical Composition (NFC) */
87
        NFC,
88
        /** Compatibility Decomposition (NFKD) */
89
        NFKD,
90
        /** Compatibility Decomposition followed by Canonical Composition (NFKC) */
91
        NFKC
92
    }
93
}
94

95
/**
96
 * Validates that character sequence is normalized according to specified form.
97
 *
98
 * Supported types: CharSequence
99
 */
100
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
101
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
102
@Retention(RetentionPolicy.RUNTIME)
103
@Constraint(validatedBy = {})
104
@interface Normalized {
105
    /**
106
     * Unicode normalization form to check against.
107
     */
108
    java.text.Normalizer.Form form();
109

110
    String message() default "{org.hibernate.validator.constraints.Normalized.message}";
111
    Class<?>[] groups() default {};
112
    Class<? extends Payload>[] payload() default {};
113
}
114

115
/**
116
 * Validates that character sequence is a valid UUID.
117
 *
118
 * Validation characteristics:
119
 * - Consists only of numbers, hex characters and dashes
120
 * - Has exact length of 36 characters
121
 * - Number of hex digits in every group (8-4-4-4-12)
122
 * - Configurable nil UUID, versions, variants, and letter case
123
 *
124
 * Supported types: CharSequence
125
 * @since 8.0.0
126
 */
127
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
128
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
129
@Retention(RetentionPolicy.RUNTIME)
130
@Constraint(validatedBy = {})
131
@interface UUID {
132
    /**
133
     * Allow empty strings. Default: false
134
     */
135
    boolean allowEmpty() default false;
136

137
    /**
138
     * Allow nil UUID (00000000-0000-0000-0000-000000000000). Default: true
139
     */
140
    boolean allowNil() default true;
141

142
    /**
143
     * Accepted UUID versions (1-15 corresponding to hex 1-f).
144
     * Default: {1, 2, 3, 4, 5}
145
     */
146
    int[] version() default {1, 2, 3, 4, 5};
147

148
    /**
149
     * Accepted UUID variants (0-2).
150
     * Default: {0, 1, 2}
151
     */
152
    int[] variant() default {0, 1, 2};
153

154
    /**
155
     * Required letter case for hex characters.
156
     * Default: LOWER_CASE
157
     */
158
    LetterCase letterCase() default LetterCase.LOWER_CASE;
159

160
    String message() default "{org.hibernate.validator.constraints.UUID.message}";
161
    Class<?>[] groups() default {};
162
    Class<? extends Payload>[] payload() default {};
163

164
    /**
165
     * Required letter case for UUID hex characters.
166
     */
167
    enum LetterCase {
168
        /** Only lower case is valid */
169
        LOWER_CASE,
170
        /** Only upper case is valid */
171
        UPPER_CASE,
172
        /** Any letter case is valid */
173
        INSENSITIVE
174
    }
175
}
176

177
/**
178
 * Validates that collection contains only unique elements.
179
 *
180
 * Supported types: Collection
181
 */
182
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
183
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
184
@Retention(RetentionPolicy.RUNTIME)
185
@Constraint(validatedBy = {})
186
@interface UniqueElements {
187
    String message() default "{org.hibernate.validator.constraints.UniqueElements.message}";
188
    Class<?>[] groups() default {};
189
    Class<? extends Payload>[] payload() default {};
190
}
191
```
192

193
**Usage Example:**
194

195
```java
196
import org.hibernate.validator.constraints.*;
197

198
public class Article {
199
    @Length(min = 10, max = 200)
200
    private String title;
201

202
    @CodePointLength(min = 1, max = 100, normalizationStrategy = CodePointLength.NormalizationStrategy.NFC)
203
    private String displayName;  // Handles emojis and special Unicode correctly
204

205
    @Normalized(form = java.text.Normalizer.Form.NFC)
206
    private String normalizedText;
207

208
    @UUID(letterCase = UUID.LetterCase.LOWER_CASE, allowNil = false, version = {4})
209
    private String articleId;
210

211
    @UniqueElements
212
    private List<String> tags;
213
}
214
```
215

216
### URL and Network Validators
217

218
URL validation with protocol, host, and port constraints.
219

220
```java { .api }
221
package org.hibernate.validator.constraints;
222

223
import jakarta.validation.Constraint;
224
import jakarta.validation.Payload;
225
import java.lang.annotation.*;
226
import java.util.regex.Pattern;
227

228
/**
229
 * Validates that annotated string is a valid URL.
230
 * Uses java.net.URL constructor by default. Can be configured
231
 * to use RegexpURLValidator for non-standard protocols.
232
 *
233
 * Supported types: CharSequence
234
 */
235
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
236
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
237
@Retention(RetentionPolicy.RUNTIME)
238
@Constraint(validatedBy = {})
239
@interface URL {
240
    /**
241
     * Required protocol (e.g., "http", "https", "ftp").
242
     * Empty string allows any protocol. Default: ""
243
     */
244
    String protocol() default "";
245

246
    /**
247
     * Required host (e.g., "localhost", "example.com").
248
     * Empty string allows any host. Default: ""
249
     */
250
    String host() default "";
251

252
    /**
253
     * Required port. -1 allows any port. Default: -1
254
     */
255
    int port() default -1;
256

257
    /**
258
     * Additional regex pattern the URL must match.
259
     * Default: ".*" (matches everything)
260
     */
261
    String regexp() default ".*";
262

263
    /**
264
     * Flags for regexp pattern matching.
265
     * Default: {} (no flags)
266
     */
267
    Pattern.Flag[] flags() default {};
268

269
    String message() default "{org.hibernate.validator.constraints.URL.message}";
270
    Class<?>[] groups() default {};
271
    Class<? extends Payload>[] payload() default {};
272
}
273
```
274

275
**Usage Example:**
276

277
```java
278
import org.hibernate.validator.constraints.URL;
279

280
public class WebResource {
281
    @URL(protocol = "https", host = "api.example.com")
282
    private String apiEndpoint;
283

284
    @URL(protocol = "http", regexp = ".*/api/.*")
285
    private String restUrl;
286

287
    @URL
288
    private String homepage;  // Any valid URL
289
}
290
```
291

292
### Numeric Range Constraints
293

294
Numeric range validation combining min and max constraints.
295

296
```java { .api }
297
package org.hibernate.validator.constraints;
298

299
import jakarta.validation.Constraint;
300
import jakarta.validation.Payload;
301
import java.lang.annotation.*;
302

303
/**
304
 * Validates that value is within specified range (inclusive).
305
 * Composed of @Min and @Max constraints.
306
 *
307
 * Supported types: BigDecimal, BigInteger, CharSequence, byte, short, int, long, and wrappers
308
 */
309
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
310
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
311
@Retention(RetentionPolicy.RUNTIME)
312
@Constraint(validatedBy = {})
313
@interface Range {
314
    /**
315
     * Minimum value (inclusive). Default: 0
316
     */
317
    long min() default 0;
318

319
    /**
320
     * Maximum value (inclusive). Default: Long.MAX_VALUE
321
     */
322
    long max() default Long.MAX_VALUE;
323

324
    String message() default "{org.hibernate.validator.constraints.Range.message}";
325
    Class<?>[] groups() default {};
326
    Class<? extends Payload>[] payload() default {};
327
}
328
```
329

330
**Usage Example:**
331

332
```java
333
import org.hibernate.validator.constraints.Range;
334

335
public class Product {
336
    @Range(min = 0, max = 100)
337
    private int discountPercent;
338

339
    @Range(min = 1, max = 999999)
340
    private long productId;
341
}
342
```
343

344
### Monetary Constraints
345

346
Currency validation for monetary amounts.
347

348
```java { .api }
349
package org.hibernate.validator.constraints;
350

351
import jakarta.validation.Constraint;
352
import jakarta.validation.Payload;
353
import java.lang.annotation.*;
354

355
/**
356
 * Validates that MonetaryAmount has the right CurrencyUnit.
357
 * Requires javax.money API on classpath.
358
 *
359
 * Supported types: javax.money.MonetaryAmount
360
 * @since 5.4
361
 */
362
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
363
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
364
@Retention(RetentionPolicy.RUNTIME)
365
@Constraint(validatedBy = {})
366
@interface Currency {
367
    /**
368
     * Currency codes that are accepted (e.g., "USD", "EUR", "GBP").
369
     * Must match the currency of the validated MonetaryAmount.
370
     */
371
    String[] value();
372

373
    String message() default "{org.hibernate.validator.constraints.Currency.message}";
374
    Class<?>[] groups() default {};
375
    Class<? extends Payload>[] payload() default {};
376
}
377
```
378

379
**Usage Example:**
380

381
```java
382
import org.hibernate.validator.constraints.Currency;
383
import javax.money.MonetaryAmount;
384
import javax.money.Monetary;
385

386
public class Payment {
387
    @Currency({"USD", "EUR"})
388
    private MonetaryAmount price;  // Only accepts USD or EUR
389

390
    @Currency("GBP")
391
    private MonetaryAmount britishPrice;  // Only accepts GBP
392
}
393
```
394

395
### Financial Validators
396

397
Credit card and cryptocurrency validation.
398

399
```java { .api }
400
package org.hibernate.validator.constraints;
401

402
import jakarta.validation.Constraint;
403
import jakarta.validation.Payload;
404
import java.lang.annotation.*;
405

406
/**
407
 * Validates credit card number using Luhn algorithm (mod 10 checksum).
408
 * Composed of @LuhnCheck constraint.
409
 *
410
 * Supported types: CharSequence
411
 */
412
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
413
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
414
@Retention(RetentionPolicy.RUNTIME)
415
@Constraint(validatedBy = {})
416
@interface CreditCardNumber {
417
    /**
418
     * Ignore non-digit characters (spaces, dashes, etc.). Default: false
419
     */
420
    boolean ignoreNonDigitCharacters() default false;
421

422
    String message() default "{org.hibernate.validator.constraints.CreditCardNumber.message}";
423
    Class<?>[] groups() default {};
424
    Class<? extends Payload>[] payload() default {};
425
}
426

427
/**
428
 * Validates Luhn checksum algorithm (mod 10).
429
 * Used for credit cards, IMEI numbers, etc.
430
 *
431
 * Supported types: CharSequence
432
 */
433
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
434
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
435
@Retention(RetentionPolicy.RUNTIME)
436
@Constraint(validatedBy = {})
437
@interface LuhnCheck {
438
    /**
439
     * Start index for checksum calculation (inclusive). Default: 0
440
     */
441
    int startIndex() default 0;
442

443
    /**
444
     * End index for checksum calculation (exclusive). Default: Integer.MAX_VALUE
445
     */
446
    int endIndex() default Integer.MAX_VALUE;
447

448
    /**
449
     * Check digit index. -1 means last digit. Default: -1
450
     */
451
    int checkDigitIndex() default -1;
452

453
    /**
454
     * Ignore non-digit characters. Default: false
455
     */
456
    boolean ignoreNonDigitCharacters() default false;
457

458
    String message() default "{org.hibernate.validator.constraints.LuhnCheck.message}";
459
    Class<?>[] groups() default {};
460
    Class<? extends Payload>[] payload() default {};
461
}
462

463

464
/**
465
 * Validates Bitcoin address format.
466
 * P2PK, P2MS and Nested SegWit (P2SH-P2WPKH and P2SH-P2WSH) addresses are not valid.
467
 *
468
 * Supported types: CharSequence
469
 * @since 9.0.0
470
 */
471
@Incubating
472
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
473
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
474
@Retention(RetentionPolicy.RUNTIME)
475
@Constraint(validatedBy = {})
476
@interface BitcoinAddress {
477
    /**
478
     * Bitcoin address types to validate.
479
     * Default: ANY (accept any valid Bitcoin address type)
480
     */
481
    BitcoinAddressType[] value() default BitcoinAddressType.ANY;
482

483
    String message() default "{org.hibernate.validator.constraints.BitcoinAddress.message}";
484
    Class<?>[] groups() default {};
485
    Class<? extends Payload>[] payload() default {};
486

487
    /**
488
     * Bitcoin address types.
489
     */
490
    enum BitcoinAddressType {
491
        /** Any valid Bitcoin address type */
492
        ANY,
493
        /** Pay to Public Key Hash (legacy address, starts with 1) */
494
        P2PKH,
495
        /** Pay to Script Hash (legacy address, starts with 3) */
496
        P2SH,
497
        /** Bech32 format (SegWit v0 for any witness program, starts with bc1) */
498
        BECH32,
499
        /** Pay to Witness Script Hash (SegWit v0, starts with bc1) */
500
        P2WSH,
501
        /** Pay to Witness Public Key Hash (SegWit v0, starts with bc1) */
502
        P2WPKH,
503
        /** Pay to Taproot (SegWit v1, starts with bc1p) */
504
        P2TR
505
    }
506
}
507
```
508

509
**Usage Example:**
510

511
```java
512
import org.hibernate.validator.constraints.*;
513

514
public class Payment {
515
    @CreditCardNumber(ignoreNonDigitCharacters = true)
516
    private String cardNumber;  // Accepts "1234-5678-9012-3456"
517

518
    @BitcoinAddress(BitcoinAddress.BitcoinAddressType.BECH32)
519
    private String bitcoinWallet;
520
}
521
```
522

523
### Checksum Validators
524

525
Generic checksum validators for various algorithms.
526

527
```java { .api }
528
package org.hibernate.validator.constraints;
529

530
import jakarta.validation.Constraint;
531
import jakarta.validation.Payload;
532
import java.lang.annotation.*;
533

534
/**
535
 * Validates generic Mod10 checksum algorithm.
536
 * Used for various identification numbers.
537
 *
538
 * Supported types: CharSequence
539
 */
540
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
541
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
542
@Retention(RetentionPolicy.RUNTIME)
543
@Constraint(validatedBy = {})
544
@interface Mod10Check {
545
    /**
546
     * Multiplier for Mod10 algorithm. Default: 3
547
     */
548
    int multiplier() default 3;
549

550
    /**
551
     * Weight for Mod10 algorithm. Default: 1
552
     */
553
    int weight() default 1;
554

555
    /**
556
     * Start index for checksum calculation. Default: 0
557
     */
558
    int startIndex() default 0;
559

560
    /**
561
     * End index for checksum calculation. Default: Integer.MAX_VALUE
562
     */
563
    int endIndex() default Integer.MAX_VALUE;
564

565
    /**
566
     * Check digit index. -1 means last digit. Default: -1
567
     */
568
    int checkDigitIndex() default -1;
569

570
    /**
571
     * Ignore non-digit characters. Default: false
572
     */
573
    boolean ignoreNonDigitCharacters() default false;
574

575
    String message() default "{org.hibernate.validator.constraints.Mod10Check.message}";
576
    Class<?>[] groups() default {};
577
    Class<? extends Payload>[] payload() default {};
578
}
579

580
/**
581
 * Validates Mod11 checksum algorithm.
582
 * Used for various identification numbers.
583
 *
584
 * Supported types: CharSequence
585
 */
586
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
587
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
588
@Retention(RetentionPolicy.RUNTIME)
589
@Constraint(validatedBy = {})
590
@interface Mod11Check {
591
    /**
592
     * Threshold for Mod11 remainder. Default: Integer.MAX_VALUE
593
     */
594
    int threshold() default Integer.MAX_VALUE;
595

596
    /**
597
     * Character to use when check digit is 10. Default: 'X'
598
     */
599
    char treatCheck10As() default 'X';
600

601
    /**
602
     * Character to use when check digit is 11. Default: '0'
603
     */
604
    char treatCheck11As() default '0';
605

606
    /**
607
     * Processing direction for checksum calculation.
608
     * Default: RIGHT_TO_LEFT
609
     */
610
    ProcessingDirection processingDirection() default ProcessingDirection.RIGHT_TO_LEFT;
611

612
    /**
613
     * Start index for checksum calculation. Default: 0
614
     */
615
    int startIndex() default 0;
616

617
    /**
618
     * End index for checksum calculation. Default: Integer.MAX_VALUE
619
     */
620
    int endIndex() default Integer.MAX_VALUE;
621

622
    /**
623
     * Check digit index. -1 means last digit. Default: -1
624
     */
625
    int checkDigitIndex() default -1;
626

627
    /**
628
     * Ignore non-digit characters. Default: false
629
     */
630
    boolean ignoreNonDigitCharacters() default false;
631

632
    String message() default "{org.hibernate.validator.constraints.Mod11Check.message}";
633
    Class<?>[] groups() default {};
634
    Class<? extends Payload>[] payload() default {};
635

636
    /**
637
     * Processing direction for Mod11 calculation.
638
     */
639
    enum ProcessingDirection {
640
        /** Process digits from left to right */
641
        LEFT_TO_RIGHT,
642
        /** Process digits from right to left */
643
        RIGHT_TO_LEFT
644
    }
645
}
646
```
647

648
### Product Identification Validators
649

650
ISBN and EAN validators for book and product identification.
651

652
```java { .api }
653
package org.hibernate.validator.constraints;
654

655
import jakarta.validation.Constraint;
656
import jakarta.validation.Payload;
657
import java.lang.annotation.*;
658

659
/**
660
 * Validates ISBN (International Standard Book Number).
661
 *
662
 * Supported types: CharSequence
663
 * @since 6.0.6
664
 */
665
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
666
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
667
@Retention(RetentionPolicy.RUNTIME)
668
@Constraint(validatedBy = {})
669
@interface ISBN {
670
    /**
671
     * ISBN format to validate.
672
     * Default: ISBN_13
673
     */
674
    Type type() default Type.ISBN_13;
675

676
    String message() default "{org.hibernate.validator.constraints.ISBN.message}";
677
    Class<?>[] groups() default {};
678
    Class<? extends Payload>[] payload() default {};
679

680
    /**
681
     * ISBN format types.
682
     */
683
    enum Type {
684
        /** ISBN-10 format (10 digits) */
685
        ISBN_10,
686
        /** ISBN-13 format (13 digits) */
687
        ISBN_13,
688
        /** Accept either ISBN-10 or ISBN-13 */
689
        ANY
690
    }
691
}
692

693
/**
694
 * Validates EAN (European Article Number).
695
 * Composed of @Mod10Check constraint.
696
 *
697
 * Supported types: CharSequence
698
 */
699
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
700
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
701
@Retention(RetentionPolicy.RUNTIME)
702
@Constraint(validatedBy = {})
703
@interface EAN {
704
    /**
705
     * EAN format to validate.
706
     * Default: EAN13
707
     */
708
    Type type() default Type.EAN13;
709

710
    String message() default "{org.hibernate.validator.constraints.EAN.message}";
711
    Class<?>[] groups() default {};
712
    Class<? extends Payload>[] payload() default {};
713

714
    /**
715
     * EAN format types.
716
     */
717
    enum Type {
718
        /** EAN-13 format (13 digits) */
719
        EAN13,
720
        /** EAN-8 format (8 digits) */
721
        EAN8
722
    }
723
}
724
```
725

726
**Usage Example:**
727

728
```java
729
import org.hibernate.validator.constraints.*;
730

731
public class Book {
732
    @ISBN(type = ISBN.Type.ISBN_13)
733
    private String isbn;
734

735
    @EAN(type = EAN.Type.EAN13)
736
    private String barcode;
737
}
738
```
739

740
### Time-Related Constraints
741

742
Duration validation for java.time.Duration.
743

744
```java { .api }
745
package org.hibernate.validator.constraints.time;
746

747
import jakarta.validation.Constraint;
748
import jakarta.validation.Payload;
749
import java.lang.annotation.*;
750

751
/**
752
 * Validates that duration is greater than or equal to specified minimum.
753
 *
754
 * Supported types: java.time.Duration
755
 */
756
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
757
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
758
@Retention(RetentionPolicy.RUNTIME)
759
@Constraint(validatedBy = {})
760
@interface DurationMin {
761
    /** Days component. Default: 0 */
762
    long days() default 0;
763

764
    /** Hours component. Default: 0 */
765
    long hours() default 0;
766

767
    /** Minutes component. Default: 0 */
768
    long minutes() default 0;
769

770
    /** Seconds component. Default: 0 */
771
    long seconds() default 0;
772

773
    /** Milliseconds component. Default: 0 */
774
    long millis() default 0;
775

776
    /** Nanoseconds component. Default: 0 */
777
    long nanos() default 0;
778

779
    /** Include boundary (minimum is valid). Default: true */
780
    boolean inclusive() default true;
781

782
    String message() default "{org.hibernate.validator.constraints.time.DurationMin.message}";
783
    Class<?>[] groups() default {};
784
    Class<? extends Payload>[] payload() default {};
785
}
786

787
/**
788
 * Validates that duration is less than or equal to specified maximum.
789
 *
790
 * Supported types: java.time.Duration
791
 */
792
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
793
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
794
@Retention(RetentionPolicy.RUNTIME)
795
@Constraint(validatedBy = {})
796
@interface DurationMax {
797
    /** Days component. Default: 0 */
798
    long days() default 0;
799

800
    /** Hours component. Default: 0 */
801
    long hours() default 0;
802

803
    /** Minutes component. Default: 0 */
804
    long minutes() default 0;
805

806
    /** Seconds component. Default: 0 */
807
    long seconds() default 0;
808

809
    /** Milliseconds component. Default: 0 */
810
    long millis() default 0;
811

812
    /** Nanoseconds component. Default: 0 */
813
    long nanos() default 0;
814

815
    /** Include boundary (maximum is valid). Default: true */
816
    boolean inclusive() default true;
817

818
    String message() default "{org.hibernate.validator.constraints.time.DurationMax.message}";
819
    Class<?>[] groups() default {};
820
    Class<? extends Payload>[] payload() default {};
821
}
822
```
823

824
**Usage Example:**
825

826
```java
827
import org.hibernate.validator.constraints.time.*;
828
import java.time.Duration;
829

830
public class Task {
831
    @DurationMin(minutes = 5)
832
    private Duration minimumDuration;
833

834
    @DurationMax(hours = 8, inclusive = true)
835
    private Duration maximumDuration;
836

837
    @DurationMin(seconds = 30)
838
    @DurationMax(hours = 2)
839
    private Duration estimatedTime;
840
}
841
```
842

843
### Script-Based Validation
844

845
Execute script expressions for complex validation logic.
846

847
```java { .api }
848
package org.hibernate.validator.constraints;
849

850
import jakarta.validation.Constraint;
851
import jakarta.validation.Payload;
852
import java.lang.annotation.*;
853

854
/**
855
 * Class-level constraint that evaluates script expression against annotated element.
856
 * Requires JSR 223 compatible script engine on classpath.
857
 *
858
 * Target: TYPE
859
 * Supported script languages: javascript, groovy, etc.
860
 */
861
@Target({ElementType.TYPE})
862
@Retention(RetentionPolicy.RUNTIME)
863
@Constraint(validatedBy = {})
864
@interface ScriptAssert {
865
    /**
866
     * Script language name (e.g., "javascript", "groovy").
867
     */
868
    String lang();
869

870
    /**
871
     * Script to execute. Must return Boolean.TRUE or Boolean.FALSE.
872
     */
873
    String script();
874

875
    /**
876
     * Name for validated object in script context.
877
     * Default: "_this"
878
     */
879
    String alias() default "_this";
880

881
    /**
882
     * Property name to report violation on.
883
     * Empty string reports on class level.
884
     * Default: "" (class level)
885
     * @since 5.4
886
     */
887
    String reportOn() default "";
888

889
    String message() default "{org.hibernate.validator.constraints.ScriptAssert.message}";
890
    Class<?>[] groups() default {};
891
    Class<? extends Payload>[] payload() default {};
892
}
893

894
/**
895
 * Cross-parameter constraint that evaluates script expression for method parameters.
896
 * Requires JSR 223 compatible script engine on classpath.
897
 *
898
 * Target: CONSTRUCTOR, METHOD
899
 */
900
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD})
901
@Retention(RetentionPolicy.RUNTIME)
902
@Constraint(validatedBy = {})
903
@interface ParameterScriptAssert {
904
    /**
905
     * Script language name.
906
     */
907
    String lang();
908

909
    /**
910
     * Script to execute. Must return Boolean.TRUE or Boolean.FALSE.
911
     */
912
    String script();
913

914
    /**
915
     * Name for parameters array in script context.
916
     * Default: "_args"
917
     */
918
    String alias() default "_args";
919

920
    String message() default "{org.hibernate.validator.constraints.ParameterScriptAssert.message}";
921
    Class<?>[] groups() default {};
922
    Class<? extends Payload>[] payload() default {};
923
}
924
```
925

926
**Usage Example:**
927

928
```java
929
import org.hibernate.validator.constraints.*;
930

931
@ScriptAssert(
932
    lang = "javascript",
933
    script = "_this.startDate.before(_this.endDate)",
934
    reportOn = "endDate",
935
    message = "End date must be after start date"
936
)
937
public class DateRange {
938
    private Date startDate;
939
    private Date endDate;
940
}
941

942
public class Calculator {
943
    @ParameterScriptAssert(
944
        lang = "javascript",
945
        script = "_args[0] < _args[1]",
946
        message = "First parameter must be less than second"
947
    )
948
    public int subtract(int a, int b) {
949
        return b - a;
950
    }
951
}
952
```
953

954
### Country-Specific Validators
955

956
Validators for country-specific identification numbers.
957

958
```java { .api }
959
// Brazilian Validators
960
package org.hibernate.validator.constraints.br;
961

962
import jakarta.validation.Constraint;
963
import jakarta.validation.Payload;
964
import java.lang.annotation.*;
965

966
/**
967
 * Validates CPF (Cadastro de Pessoa Física) - Brazilian individual taxpayer number.
968
 * Supported types: CharSequence
969
 */
970
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
971
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
972
@Retention(RetentionPolicy.RUNTIME)
973
@Constraint(validatedBy = {})
974
@interface CPF {
975
    String message() default "{org.hibernate.validator.constraints.br.CPF.message}";
976
    Class<?>[] groups() default {};
977
    Class<? extends Payload>[] payload() default {};
978
}
979

980
/**
981
 * Validates CNPJ (Cadastro Nacional da Pessoa Jurídica) - Brazilian company registry number.
982
 * Supported types: CharSequence
983
 */
984
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
985
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
986
@Retention(RetentionPolicy.RUNTIME)
987
@Constraint(validatedBy = {})
988
@interface CNPJ {
989
    /**
990
     * Format type of the CNPJ number to be considered as valid.
991
     * Default: NUMERIC
992
     */
993
    @Incubating
994
    Format format() default Format.NUMERIC;
995

996
    String message() default "{org.hibernate.validator.constraints.br.CNPJ.message}";
997
    Class<?>[] groups() default {};
998
    Class<? extends Payload>[] payload() default {};
999

1000
    /**
1001
     * CNPJ format types.
1002
     */
1003
    enum Format {
1004
        /**
1005
         * Older, original CNPJ format constructed from digits only.
1006
         * Format: dd.ddd.ddd/dddd-dd (where d represents a digit)
1007
         */
1008
        NUMERIC,
1009
        /**
1010
         * New CNPJ format with digits and ASCII letters.
1011
         * Format: ss.sss.sss/ssss-dd (where s represents a digit or letter, d represents a digit)
1012
         * Adoption starts in January 2026.
1013
         */
1014
        ALPHANUMERIC
1015
    }
1016
}
1017

1018
/**
1019
 * Validates Título Eleitoral - Brazilian voter ID card number.
1020
 * Supported types: CharSequence
1021
 */
1022
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1023
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1024
@Retention(RetentionPolicy.RUNTIME)
1025
@Constraint(validatedBy = {})
1026
@interface TituloEleitoral {
1027
    String message() default "{org.hibernate.validator.constraints.br.TituloEleitoral.message}";
1028
    Class<?>[] groups() default {};
1029
    Class<? extends Payload>[] payload() default {};
1030
}
1031

1032
// Polish Validators
1033
package org.hibernate.validator.constraints.pl;
1034

1035
/**
1036
 * Validates NIP (Numer Identyfikacji Podatkowej) - Polish Tax Identification Number.
1037
 * Supported types: CharSequence
1038
 */
1039
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1040
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1041
@Retention(RetentionPolicy.RUNTIME)
1042
@Constraint(validatedBy = {})
1043
@interface NIP {
1044
    String message() default "{org.hibernate.validator.constraints.pl.NIP.message}";
1045
    Class<?>[] groups() default {};
1046
    Class<? extends Payload>[] payload() default {};
1047
}
1048

1049
/**
1050
 * Validates PESEL - Polish national identification number.
1051
 * Supported types: CharSequence
1052
 */
1053
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1054
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1055
@Retention(RetentionPolicy.RUNTIME)
1056
@Constraint(validatedBy = {})
1057
@interface PESEL {
1058
    String message() default "{org.hibernate.validator.constraints.pl.PESEL.message}";
1059
    Class<?>[] groups() default {};
1060
    Class<? extends Payload>[] payload() default {};
1061
}
1062

1063
/**
1064
 * Validates REGON (Rejestr Gospodarki Narodowej) - Polish business registry number.
1065
 * Supported types: CharSequence
1066
 */
1067
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1068
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1069
@Retention(RetentionPolicy.RUNTIME)
1070
@Constraint(validatedBy = {})
1071
@interface REGON {
1072
    String message() default "{org.hibernate.validator.constraints.pl.REGON.message}";
1073
    Class<?>[] groups() default {};
1074
    Class<? extends Payload>[] payload() default {};
1075
}
1076

1077
// Russian Validators
1078
package org.hibernate.validator.constraints.ru;
1079

1080
/**
1081
 * Validates INN (Идентификационный номер налогоплательщика) - Russian Taxpayer ID.
1082
 * Supported types: CharSequence
1083
 */
1084
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1085
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1086
@Retention(RetentionPolicy.RUNTIME)
1087
@Constraint(validatedBy = {})
1088
@interface INN {
1089
    String message() default "{org.hibernate.validator.constraints.ru.INN.message}";
1090
    Class<?>[] groups() default {};
1091
    Class<? extends Payload>[] payload() default {};
1092
}
1093

1094
// Korean Validators
1095
package org.hibernate.validator.constraints.kor;
1096

1097
/**
1098
 * Validates Korean Resident Registration Number.
1099
 * Supported types: CharSequence
1100
 */
1101
@Target({ElementType.METHOD, ElementType.FIELD, ElementType.ANNOTATION_TYPE,
1102
         ElementType.CONSTRUCTOR, ElementType.PARAMETER, ElementType.TYPE_USE})
1103
@Retention(RetentionPolicy.RUNTIME)
1104
@Constraint(validatedBy = {})
1105
@interface KorRRN {
1106
    String message() default "{org.hibernate.validator.constraints.kor.KorRRN.message}";
1107
    Class<?>[] groups() default {};
1108
    Class<? extends Payload>[] payload() default {};
1109
}
1110
```
1111

1112
**Usage Example:**
1113

1114
```java
1115
import org.hibernate.validator.constraints.br.*;
1116
import org.hibernate.validator.constraints.pl.*;
1117
import org.hibernate.validator.constraints.ru.*;
1118
import org.hibernate.validator.constraints.kor.*;
1119

1120
public class InternationalPerson {
1121
    @CPF
1122
    private String brazilianCPF;
1123

1124
    @CNPJ
1125
    private String brazilianCompanyNumber;
1126

1127
    @NIP
1128
    private String polishTaxId;
1129

1130
    @PESEL
1131
    private String polishNationalId;
1132

1133
    @INN
1134
    private String russianTaxId;
1135

1136
    @KorRRN
1137
    private String koreanResidentNumber;
1138
}
1139
```
1140

1141
### Constraint Composition
1142

1143
Control how composed constraints are evaluated.
1144

1145
```java { .api }
1146
package org.hibernate.validator.constraints;
1147

1148
import java.lang.annotation.*;
1149

1150
/**
1151
 * Defines boolean operator for composing constraint annotations.
1152
 * Applied to constraint annotation types.
1153
 *
1154
 * Target: ANNOTATION_TYPE
1155
 */
1156
@Target({ElementType.ANNOTATION_TYPE})
1157
@Retention(RetentionPolicy.RUNTIME)
1158
@interface ConstraintComposition {
1159
    /**
1160
     * Composition type for constraint evaluation.
1161
     * Default: AND (all constraints must pass)
1162
     */
1163
    CompositionType value() default CompositionType.AND;
1164
}
1165

1166
/**
1167
 * Composition types for constraint evaluation.
1168
 */
1169
enum CompositionType {
1170
    /**
1171
     * All constraints must be satisfied (conjunction).
1172
     * This is the default behavior.
1173
     */
1174
    AND,
1175

1176
    /**
1177
     * At least one constraint must be satisfied (disjunction).
1178
     */
1179
    OR,
1180

1181
    /**
1182
     * All constraints must fail (negation of conjunction).
1183
     * Used for "not valid" scenarios.
1184
     */
1185
    ALL_FALSE
1186
}
1187
```
1188

1189
**Usage Example:**
1190

1191
```java
1192
import org.hibernate.validator.constraints.*;
1193
import jakarta.validation.constraints.*;
1194

1195
// Custom composed constraint using OR logic
1196
@ConstraintComposition(CompositionType.OR)
1197
@Pattern(regexp = "[0-9]+")
1198
@Size(min = 5)
1199
@Target({ElementType.FIELD, ElementType.METHOD})
1200
@Retention(RetentionPolicy.RUNTIME)
1201
@Constraint(validatedBy = {})
1202
public @interface NumericOrLong {
1203
    String message() default "Must be numeric OR at least 5 characters";
1204
    Class<?>[] groups() default {};
1205
    Class<? extends Payload>[] payload() default {};
1206
}
1207

1208
public class Example {
1209
    @NumericOrLong  // Valid if: all digits OR length >= 5
1210
    private String value;
1211
}
1212
```
1213