Validator, Errors and DataBinder

BeanValidator checks an object against its constraint annotations, Errors holds what went wrong, and DataBinder fills an object from text input before checking it.

Why you need them

The constraint annotations only describe rules. Something has to run them and give you the result in a form you can use:

• a list of violations with finished messages, for logs or your own response format: BeanValidator.validateObject;
• an Errors object with message codes, so a message file can word each error in the user's language: BeanValidator as a Validator;
• a full round trip from form fields or query parameters (strings) to a checked object: DataBinder.

You do not need to call them yourself for @Valid() request bodies, @Validated() beans and @Validated() configuration properties: the framework does it.

BeanValidator

BeanValidator reads the constraints of @Introspected() classes. Create it with the context's BeanIntrospector: the default introspector, BeanIntrospector.shared, does not know the classes of your application modules.

import 'package:spring_core_dart/spring_core_dart.dart';

const log = SpringLog('import');

@Service()
class CustomerImport {
  // The context registers its BeanIntrospector as a bean.
  CustomerImport(BeanIntrospector introspector)
    : _validator = BeanValidator(introspector: introspector);

  final BeanValidator _validator;

  // Rows from a file do not pass through a controller: check them here.
  bool accept(CustomerRow row) {
    final violations = _validator.validateObject(row);
    for (final v in violations) {
      log.warning('${v.propertyPath}: ${v.message}'); // name: must not be blank
    }
    return violations.isEmpty;
  }
}

With spring_boot_dart, a BeanValidator bean named defaultValidator already exists. Inject BeanValidator or Validator instead of creating one.

Constructor

Methods

// Check one field as the user leaves it.
final nameProblems = validator.validateProperty(form, 'name');

// Check input before an object exists.
final ageProblems = validator.validateValue(SignupForm, 'age', 12);

ConstraintViolation

Messages

Messages are filled in this order:

1. {key} placeholders are looked up in validationMessageSource. The built-in messages are also available under jakarta.validation.constraints.<Name>.message, so a message source can replace them.
2. {attribute} placeholders take the constraint's attributes ({min}, {max}, {value}).
3. ${validatedValue} takes the invalid value.

\{, \}, \$ and \\ stay literal characters.

// Replace the built-in NotBlank text and use a key in a custom message.
final messages = StaticMessageSource()
  ..addMessage('jakarta.validation.constraints.NotBlank.message', '', 'please fill in')
  ..addMessage('nick.size', '', 'at least {min} letters');

final validator = BeanValidator(
  introspector: introspector,
  validationMessageSource: messages,
);

You do not need validationMessageSource for keys such as NotBlank.signup.name in messages.properties. Those word field errors when they are shown through the application's message source.

Validator: rules in code

Write a Validator for rules that do not fit an annotation: a value that depends on another one, or a lookup. It receives the object and records problems in an Errors.

// Two fields must agree: written in code instead of as an annotation.
class SignupValidator implements Validator {
  @override
  bool supports(Object target) => target is SignupForm;

  @override
  void validate(Object target, Errors errors) {
    ValidationUtils.rejectIfEmptyOrWhitespace(errors, 'name', 'required');
    final form = target as SignupForm;
    if (form.password != form.confirm) {
      errors.rejectValue('confirm', 'mismatch');
    }
  }
}

SmartValidator adds validateWithGroups(target, errors, groups). BeanValidator implements it.

If you register a Validator as a bean, the web starter checks @Valid() arguments with the single Validator bean. With a second one and neither marked @Primary, those arguments are not checked.

ValidationUtils

Errors and BindingResult

Errors is the list of errors for one object, and the way a validator records them. BindingResult adds the target object. The usual implementations are BeanPropertyBindingResult(target, objectName) and MapBindingResult(map, objectName).

// Run two validators into one result and read it.
final result = BeanPropertyBindingResult(form, 'signup');
ValidationUtils.invokeValidator(validator, form, result);
ValidationUtils.invokeValidator(SignupValidator(), form, result);

if (result.hasErrors) {
  for (final error in result.fieldErrors()) {
    // NotBlank.signup.name, NotBlank.name, NotBlank.String, NotBlank
    log.info('${error.field}: ${error.codes}');
  }
}

Recording errors

Reading errors

ObjectError and FieldError

An error has no fixed text. It carries message codes, from the most specific to the plain one, plus arguments and a default message. A MessageSource turns it into text with the first code it defines.

// Word an error with the application's messages.properties:
// Min={0} must be at least {1}
final error = result.fieldError('age')!;
final text = context.getMessageFromResolvable(error); // age must be at least 18

Codes follow Spring's scheme. For the constraint NotBlank on field name of object signup, of type String: NotBlank.signup.name, NotBlank.name, NotBlank.String, NotBlank. DefaultMessageCodesResolver(prefix: 'validation.', postfixFormat: true) changes the scheme; implement MessageCodesResolver to use your own.

DataBinder

DataBinder copies input values, usually strings, onto the properties of an @Introspected() object, then runs its validators. Every problem ends up in one bindingResult. Text that cannot be converted becomes a typeMismatch field error that keeps what was typed, instead of an exception.

Use it when the input is a flat map of strings: form fields, query parameters, a CSV row. JSON request bodies do not need it; they are read by the ObjectMapper and checked with @Valid().

// A signup form: `email` is required, the client may never set `id`.
final introspector = context.getBean<BeanIntrospector>();
final binder = DataBinder(SignupForm(), objectName: 'signup', introspector: introspector)
  ..requiredFields = ['email']
  ..disallowedFields = ['id']
  ..validators.add(BeanValidator(introspector: introspector))
  ..bind({'name': 'Ada', 'age': 'old', 'address.city': 'Oslo'})
  ..validate();

final result = binder.bindingResult;
result.fieldError('age')!.codes.first; // typeMismatch.signup.age
result.fieldError('email')!.code; // required
binder.suppressedFields; // fields skipped by allowed/disallowed rules

close() ends binding: it throws a BindException when there are errors, else returns a model map with the target under objectName and the result under BindingResult.<objectName>.

Constructor

Settings

Methods

Immutable classes

A class with final fields and no setters cannot be bound onto. Create it from the values with construct instead:

// Start without a target; construct calls Book's constructor.
final binder = DataBinder(null, objectName: 'book', introspector: introspector)
  ..targetType = Book
  ..construct(MapValueResolver({'isbn': '978-0', 'title': 'Dune'}));

final book = binder.target as Book?; // null when a value was invalid

In Spring (Java)

LocalValidatorFactoryBean validator = new LocalValidatorFactoryBean();
validator.afterPropertiesSet();

DataBinder binder = new DataBinder(form, "signup");
binder.setRequiredFields("email");
binder.setDisallowedFields("id");
binder.setValidator(validator);
binder.bind(new MutablePropertyValues(Map.of("name", "Ada", "age", "17")));
binder.validate();
BindingResult result = binder.getBindingResult();

Differences that matter:

• BeanValidator plays both roles of LocalValidatorFactoryBean: Jakarta's validator.validate(object) is validateObject, and Spring's validate(target, errors) is validate.
• Validator.supports receives the object, not a Class, because Dart cannot test a Type for subtypes.
• DataBinder.bind takes a Map<String, Object?> instead of PropertyValues, and settings are fields (requiredFields = [...]) instead of setters.
• Validation groups are passed as groups: instead of validation hints.
• Classes must be @Introspected(); there is no reflection.

See also

• Validation overview
• Constraints
• Method validation
• Type conversion
• Application context