0
# Jakarta Validation API
1
2
Jakarta Validation API provides a comprehensive framework for validating JavaBean objects and method parameters through annotations and constraint definitions. It offers a rich set of built-in validation constraints and enables developers to create custom validation logic with detailed error reporting and internationalization capabilities.
3
4
## Package Information
5
6
- **Package Name**: jakarta.validation-api
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**:
10
```xml
11
<dependency>
12
<groupId>jakarta.validation</groupId>
13
<artifactId>jakarta.validation-api</artifactId>
14
<version>3.1.1</version>
15
</dependency>
16
```
17
18
## Core Imports
19
20
```java
21
import jakarta.validation.Validation;
22
import jakarta.validation.Validator;
23
import jakarta.validation.ValidatorFactory;
24
import jakarta.validation.ConstraintViolation;
25
import jakarta.validation.Valid;
26
import jakarta.validation.Path;
27
import jakarta.validation.Configuration;
28
import jakarta.validation.executable.ExecutableValidator;
29
import jakarta.validation.constraints.*;
30
```
31
32
## Basic Usage
33
34
```java
35
import jakarta.validation.*;
36
import jakarta.validation.constraints.*;
37
import java.util.Set;
38
39
// Define a bean with validation constraints
40
class User {
41
@NotNull
42
@Size(min = 2, max = 50)
43
private String name;
44
45
@Min(18)
46
private int age;
47
48
49
private String email;
50
51
// Constructors, getters, setters...
52
}
53
54
// Validate the bean
55
ValidatorFactory factory = Validation.buildDefaultValidatorFactory();
56
Validator validator = factory.getValidator();
57
58
User user = new User("", 15, "invalid-email");
59
Set<ConstraintViolation<User>> violations = validator.validate(user);
60
61
for (ConstraintViolation<User> violation : violations) {
62
System.out.println(violation.getPropertyPath() + ": " + violation.getMessage());
63
}
64
```
65
66
## Architecture
67
68
Jakarta Validation API is built around several key components:
69
70
- **Bootstrap API**: Entry point classes (`Validation`, `Configuration`) for setting up validation
71
- **Validation Engine**: Core interfaces (`Validator`, `ValidatorFactory`) for performing validation
72
- **Constraint Framework**: Annotation-based constraints (`@NotNull`, `@Size`, etc.) and custom constraint definition
73
- **Metadata API**: Descriptor interfaces providing validation metadata and introspection
74
- **Method Validation**: Support for validating method parameters and return values
75
- **Value Extraction**: Container element validation for generic types like `List<@NotNull String>`
76
- **SPI**: Service Provider Interface for pluggable validation implementations
77
78
## Capabilities
79
80
### Bootstrap and Configuration
81
82
Core API for setting up and configuring the validation framework with factories and context objects.
83
84
```java { .api }
85
class Validation {
86
static ValidatorFactory buildDefaultValidatorFactory();
87
static GenericBootstrap byDefaultProvider();
88
static <T extends Configuration<T>, U extends ValidationProvider<T>>
89
ProviderSpecificBootstrap<T> byProvider(Class<U> providerType);
90
}
91
92
interface ValidatorFactory extends AutoCloseable {
93
Validator getValidator();
94
ValidatorContext usingContext();
95
MessageInterpolator getMessageInterpolator();
96
TraversableResolver getTraversableResolver();
97
ConstraintValidatorFactory getConstraintValidatorFactory();
98
ParameterNameProvider getParameterNameProvider();
99
ClockProvider getClockProvider();
100
<T> T unwrap(Class<T> type);
101
void close();
102
}
103
104
interface ValidatorContext {
105
ValidatorContext messageInterpolator(MessageInterpolator messageInterpolator);
106
ValidatorContext traversableResolver(TraversableResolver traversableResolver);
107
ValidatorContext constraintValidatorFactory(ConstraintValidatorFactory factory);
108
ValidatorContext parameterNameProvider(ParameterNameProvider parameterNameProvider);
109
ValidatorContext clockProvider(ClockProvider clockProvider);
110
Validator getValidator();
111
}
112
113
interface GenericBootstrap {
114
GenericBootstrap providerResolver(ValidationProviderResolver resolver);
115
Configuration<?> configure();
116
}
117
118
interface ProviderSpecificBootstrap<T extends Configuration<T>> {
119
ProviderSpecificBootstrap<T> providerResolver(ValidationProviderResolver resolver);
120
T configure();
121
}
122
123
interface Configuration<T extends Configuration<T>> {
124
T ignoreXmlConfiguration();
125
T messageInterpolator(MessageInterpolator interpolator);
126
T traversableResolver(TraversableResolver resolver);
127
T constraintValidatorFactory(ConstraintValidatorFactory constraintValidatorFactory);
128
T parameterNameProvider(ParameterNameProvider parameterNameProvider);
129
T clockProvider(ClockProvider clockProvider);
130
T addValueExtractor(ValueExtractor<?> extractor);
131
T addMapping(InputStream stream);
132
T addProperty(String name, String value);
133
MessageInterpolator getDefaultMessageInterpolator();
134
TraversableResolver getDefaultTraversableResolver();
135
ConstraintValidatorFactory getDefaultConstraintValidatorFactory();
136
ParameterNameProvider getDefaultParameterNameProvider();
137
ClockProvider getDefaultClockProvider();
138
BootstrapConfiguration getBootstrapConfiguration();
139
ValidatorFactory buildValidatorFactory();
140
}
141
142
interface BootstrapConfiguration {
143
String getDefaultProviderClassName();
144
List<String> getConstraintValidatorFactoryClassName();
145
List<String> getMessageInterpolatorClassName();
146
List<String> getTraversableResolverClassName();
147
List<String> getParameterNameProviderClassName();
148
List<String> getClockProviderClassName();
149
List<String> getValueExtractorClassNames();
150
Set<String> getConstraintMappingResourcePaths();
151
Map<String, String> getProperties();
152
Set<ExecutableType> getExecutableValidation();
153
boolean isExecutableValidationEnabled();
154
}
155
```
156
157
[Bootstrap and Configuration](./bootstrap-configuration.md)
158
159
### Bean Validation
160
161
Primary validation interface for validating JavaBean objects, properties, and values with comprehensive constraint violation reporting.
162
163
```java { .api }
164
interface Validator {
165
<T> Set<ConstraintViolation<T>> validate(T object, Class<?>... groups);
166
<T> Set<ConstraintViolation<T>> validateProperty(T object, String propertyName, Class<?>... groups);
167
<T> Set<ConstraintViolation<T>> validateValue(Class<T> beanType, String propertyName, Object value, Class<?>... groups);
168
BeanDescriptor getConstraintsForClass(Class<?> clazz);
169
ExecutableValidator forExecutables();
170
<T> T unwrap(Class<T> type);
171
}
172
173
interface ConstraintViolation<T> {
174
String getMessage();
175
String getMessageTemplate();
176
T getRootBean();
177
Class<T> getRootBeanClass();
178
Object getLeafBean();
179
Object[] getExecutableParameters();
180
Object getExecutableReturnValue();
181
Path getPropertyPath();
182
Object getInvalidValue();
183
ConstraintDescriptor<?> getConstraintDescriptor();
184
<U> U unwrap(Class<U> type);
185
}
186
```
187
188
[Bean Validation](./bean-validation.md)
189
190
### Built-in Constraints
191
192
Comprehensive set of pre-defined constraint annotations for common validation scenarios including null checks, size validation, numeric ranges, and format validation.
193
194
```java { .api }
195
// Null value constraints
196
@interface NotNull { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
197
@interface Null { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
198
199
// String/Collection constraints
200
@interface NotEmpty { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
201
@interface NotBlank { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
202
@interface Size { int min() default 0; int max() default Integer.MAX_VALUE; String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
203
204
// Numeric constraints
205
@interface Min { long value(); String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
206
@interface Max { long value(); String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
207
@interface DecimalMin { String value(); boolean inclusive() default true; String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
208
@interface DecimalMax { String value(); boolean inclusive() default true; String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
209
@interface Positive { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
210
@interface PositiveOrZero { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
211
@interface Negative { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
212
@interface NegativeOrZero { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
213
@interface Digits { int integer(); int fraction(); String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
214
215
// Date/Time constraints
216
@interface Future { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
217
@interface FutureOrPresent { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
218
@interface Past { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
219
@interface PastOrPresent { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
220
221
// Boolean constraints
222
@interface AssertTrue { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
223
@interface AssertFalse { String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
224
225
// Format constraints
226
@interface Email { String regexp() default ".*"; Pattern.Flag[] flags() default {}; String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
227
@interface Pattern { String regexp(); Pattern.Flag[] flags() default {}; String message() default "..."; Class<?>[] groups() default {}; Class<? extends Payload>[] payload() default {}; }
228
229
enum Pattern.Flag {
230
UNIX_LINES, CASE_INSENSITIVE, COMMENTS, MULTILINE, DOTALL, UNICODE_CASE, CANON_EQ
231
}
232
```
233
234
[Built-in Constraints](./constraints.md)
235
236
### Custom Constraints
237
238
Framework for defining custom validation constraints through annotations and validator implementations with support for composed constraints.
239
240
```java { .api }
241
@interface Constraint {
242
Class<? extends ConstraintValidator<?, ?>>[] validatedBy();
243
}
244
245
interface ConstraintValidator<A extends Annotation, T> {
246
default void initialize(A constraintAnnotation) {}
247
boolean isValid(T value, ConstraintValidatorContext context);
248
}
249
250
interface ConstraintValidatorContext {
251
void disableDefaultConstraintViolation();
252
String getDefaultConstraintMessageTemplate();
253
ClockProvider getClockProvider();
254
ConstraintViolationBuilder buildConstraintViolationWithTemplate(String messageTemplate);
255
<T> T unwrap(Class<T> type);
256
}
257
258
@interface Valid {}
259
@interface ReportAsSingleViolation {}
260
@interface OverridesAttribute {
261
String constraint();
262
String name();
263
int constraintIndex() default -1;
264
}
265
@interface SupportedValidationTarget {
266
ValidationTarget[] value();
267
}
268
```
269
270
[Custom Constraints](./custom-constraints.md)
271
272
### Method Validation
273
274
Validation support for method parameters, return values, and constructor parameters with cross-parameter constraint capabilities.
275
276
```java { .api }
277
interface ExecutableValidator {
278
<T> Set<ConstraintViolation<T>> validateParameters(T object, Method method, Object[] parameterValues, Class<?>... groups);
279
<T> Set<ConstraintViolation<T>> validateReturnValue(T object, Method method, Object returnValue, Class<?>... groups);
280
<T> Set<ConstraintViolation<T>> validateConstructorParameters(Constructor<? extends T> constructor, Object[] parameterValues, Class<?>... groups);
281
<T> Set<ConstraintViolation<T>> validateConstructorReturnValue(Constructor<? extends T> constructor, T createdObject, Class<?>... groups);
282
}
283
284
enum ExecutableType {
285
IMPLICIT, NONE, CONSTRUCTORS, NON_GETTER_METHODS, GETTER_METHODS, ALL
286
}
287
288
@interface ValidateOnExecution {
289
ExecutableType[] type() default {ExecutableType.IMPLICIT};
290
}
291
```
292
293
[Method Validation](./method-validation.md)
294
295
### Validation Groups
296
297
Group-based validation for conditional constraint application and validation sequencing with group conversion support.
298
299
```java { .api }
300
interface Default {}
301
302
@interface GroupSequence {
303
Class<?>[] value();
304
}
305
306
@interface ConvertGroup {
307
Class<?> from();
308
Class<?> to();
309
}
310
```
311
312
[Validation Groups](./validation-groups.md)
313
314
### Container Element Validation
315
316
Value extraction and validation for generic container types like collections and optionals with type-safe constraint application.
317
318
```java { .api }
319
interface ValueExtractor<T> {
320
void extractValues(T originalValue, ValueReceiver receiver);
321
322
interface ValueReceiver {
323
void value(String nodeName, Object object);
324
void iterableValue(String nodeName, Object object);
325
void indexedValue(String nodeName, int index, Object object);
326
void keyedValue(String nodeName, Object key, Object object);
327
}
328
}
329
330
@interface ExtractedValue {
331
Class<?> type() default Object.class;
332
}
333
334
@interface UnwrapByDefault {}
335
```
336
337
[Container Element Validation](./container-validation.md)
338
339
### Validation Metadata
340
341
Comprehensive metadata API providing descriptors and introspection capabilities for validation constraints and bean structure.
342
343
```java { .api }
344
interface BeanDescriptor extends ElementDescriptor {
345
boolean isBeanConstrained();
346
PropertyDescriptor getPropertyDescriptor(String propertyName);
347
Set<PropertyDescriptor> getConstrainedProperties();
348
MethodDescriptor getMethodDescriptor(String methodName, Class<?>... parameterTypes);
349
Set<MethodDescriptor> getConstrainedMethods(MethodType methodType, MethodType... methodTypes);
350
ConstructorDescriptor getConstructorDescriptor(Class<?>... parameterTypes);
351
Set<ConstructorDescriptor> getConstrainedConstructors();
352
}
353
354
interface ConstraintDescriptor<T extends Annotation> {
355
T getAnnotation();
356
String getMessageTemplate();
357
Set<Class<?>> getGroups();
358
Set<Class<? extends Payload>> getPayload();
359
List<Class<? extends ConstraintValidator<T, ?>>> getConstraintValidatorClasses();
360
Map<String, Object> getAttributes();
361
Set<ConstraintDescriptor<?>> getComposingConstraints();
362
}
363
```
364
365
[Validation Metadata](./metadata.md)
366
367
### Service Provider Interface
368
369
Service Provider Interface (SPI) for pluggable validation provider implementations and bootstrap configuration.
370
371
```java { .api }
372
interface ValidationProvider<T extends Configuration<T>> {
373
T createSpecializedConfiguration(BootstrapState state);
374
Configuration<?> createGenericConfiguration(BootstrapState state);
375
ValidatorFactory buildValidatorFactory(ConfigurationState configurationState);
376
}
377
378
interface BootstrapState {
379
ValidationProviderResolver getValidationProviderResolver();
380
ValidationProviderResolver getDefaultValidationProviderResolver();
381
}
382
383
interface ConfigurationState {
384
boolean isIgnoreXmlConfiguration();
385
MessageInterpolator getMessageInterpolator();
386
Set<InputStream> getMappingStreams();
387
Set<ValueExtractor<?>> getValueExtractors();
388
ConstraintValidatorFactory getConstraintValidatorFactory();
389
TraversableResolver getTraversableResolver();
390
ParameterNameProvider getParameterNameProvider();
391
ClockProvider getClockProvider();
392
Map<String, String> getProperties();
393
}
394
395
interface ValidationProviderResolver {
396
List<ValidationProvider<?>> getValidationProviders();
397
}
398
```
399
400
## Types
401
402
```java { .api }
403
// Core exception hierarchy
404
class ValidationException extends RuntimeException {}
405
class ConstraintViolationException extends ValidationException {
406
Set<ConstraintViolation<?>> getConstraintViolations();
407
}
408
class ConstraintDeclarationException extends ValidationException {}
409
class ConstraintDefinitionException extends ValidationException {}
410
class GroupDefinitionException extends ValidationException {}
411
class NoProviderFoundException extends ValidationException {}
412
class UnexpectedTypeException extends ValidationException {}
413
class ValueExtractorDeclarationException extends ValidationException {}
414
class ValueExtractorDefinitionException extends ValidationException {}
415
416
// Supporting component interfaces
417
interface MessageInterpolator {
418
String interpolate(String messageTemplate, Context context);
419
String interpolate(String messageTemplate, Context context, Locale locale);
420
421
interface Context {
422
ConstraintDescriptor<?> getConstraintDescriptor();
423
Object getValidatedValue();
424
<T> T unwrap(Class<T> type);
425
}
426
}
427
428
interface TraversableResolver {
429
boolean isReachable(Object traversableObject, Path.Node traversableProperty, Class<?> rootBeanType, Path pathToTraversableObject, ElementType elementType);
430
boolean isCascadable(Object traversableObject, Path.Node traversableProperty, Class<?> rootBeanType, Path pathToTraversableObject, ElementType elementType);
431
}
432
433
interface ParameterNameProvider {
434
List<String> getParameterNames(Constructor<?> constructor);
435
List<String> getParameterNames(Method method);
436
}
437
438
interface ClockProvider {
439
Clock getClock();
440
}
441
442
interface ConstraintValidatorFactory {
443
<T extends ConstraintValidator<?, ?>> T getInstance(Class<T> key);
444
void releaseInstance(ConstraintValidator<?, ?> instance);
445
}
446
447
// Path navigation
448
interface Path extends Iterable<Path.Node> {
449
String toString();
450
451
interface Node {
452
String getName();
453
boolean isInIterable();
454
Integer getIndex();
455
Object getKey();
456
ElementKind getKind();
457
<T extends Path.Node> T as(Class<T> nodeType);
458
String toString();
459
}
460
461
interface BeanNode extends Node {}
462
interface PropertyNode extends Node {}
463
interface MethodNode extends Node {
464
List<Class<?>> getParameterTypes();
465
}
466
interface ConstructorNode extends Node {
467
List<Class<?>> getParameterTypes();
468
}
469
interface ParameterNode extends Node {
470
int getParameterIndex();
471
}
472
interface CrossParameterNode extends Node {}
473
interface ReturnValueNode extends Node {}
474
interface ContainerElementNode extends Node {
475
Class<?> getContainerClass();
476
Integer getTypeArgumentIndex();
477
}
478
}
479
480
// Element classification
481
enum ElementKind {
482
BEAN, PROPERTY, METHOD, CONSTRUCTOR, PARAMETER, CROSS_PARAMETER, RETURN_VALUE, CONTAINER_ELEMENT
483
}
484
485
// Constraint targeting
486
enum ConstraintTarget {
487
IMPLICIT, PARAMETERS, RETURN_VALUE
488
}
489
490
// Validation targeting
491
enum ValidationTarget {
492
ANNOTATED_ELEMENT, PARAMETERS
493
}
494
495
// Method types for metadata
496
enum MethodType {
497
GETTER, NON_GETTER
498
}
499
500
// Value extraction configuration
501
enum Unwrapping {
502
AUTOMATIC, SKIP
503
}
504
505
enum ValidateUnwrappedValue {
506
DEFAULT, SKIP, UNWRAP
507
}
508
509
// Payload marker
510
interface Payload {}
511
```