Constraints

制約は、@NotBlank() や @Min(18) のように、プロパティに対するルールを 1 つ表すアノテーションです。

なぜ必要か

制約を使うと、ルールが守るべきデータのすぐ隣に置かれます。1 つの宣言が、そのクラスを検証するすべての場所で使われます。フォーム、リクエストボディ、メソッド引数などです。バリデータは破られたルールごとに制約の名前をエラーコードとして報告するので、messages.properties でメッセージの文言を決められます。

制約を付けられる場所:

• @Introspected() クラスのプロパティ
• プロパティ同士を比べるルールのための、クラスそのもの(独自の制約)
• @Validated() Bean のパラメータやメソッド(メソッドバリデーション を参照)

すべての制約に共通するルール

• ほとんどの制約は null を通します。値が必須なら @NotNull() を加えます。
• すべての制約は次の 2 つの名前付きパラメータを取ります。

• 検証できない型に付けた制約(int に @Size、List に @NotBlank)はビルドエラーになります。dynamic や Object のプロパティでは、実行時に UnexpectedTypeException が投げられます。
• 不正なパラメータ(Size(min: -1)、壊れた正規表現)では ConstraintDeclarationException が投げられます。

// A custom message with placeholders.
@Introspected()
class Profile {
  @Size(max: 3, message: r'"${validatedValue}" is longer than {max}')
  String code = '';
}

存在

@NotNull

値を必須にします。null は失敗し、それ以外は通ります。

@Introspected()
class Signup {
  // The email may be missing in the input, but not in a valid signup.
  @NotNull()
  String? email;
}

エラーコード NotNull。デフォルトメッセージ: must not be null。パラメータ: message、groups。

@MustBeNull

値が null であることを求めます。通常は 1 つのグループに限定して使います。たとえば、レコード作成時にクライアントが送ってはいけない id です。

abstract final class OnCreate {}

@Introspected()
class NewUser {
  // The database assigns the id; the client must not send one.
  @MustBeNull(groups: [OnCreate])
  int? id;
}

エラーコード Null(Jakarta の名前。Null は Dart のコア型です)。デフォルトメッセージ: must be null。パラメータ: message、groups。

@NotEmpty

null でも空でもない文字列、リスト、セット、マップを求めます。テキストには ' ' も拒否する @NotBlank のほうが通常は適しています。

@Introspected()
class Cart {
  // A cart cannot be ordered empty.
  @NotEmpty()
  List<String> items = [];
}

エラーコード NotEmpty。デフォルトメッセージ: must not be empty。対応する型: String、Iterable、Map。パラメータ: message、groups。

@NotBlank

見える文字を 1 文字以上含むテキストを求めます。null、''、' ' は失敗します。「見える」とは、Java の String.trim() と同じく U+0020 より大きい文字を指します。

@Introspected()
class Signup {
  // A name of only spaces is not a name.
  @NotBlank()
  String name = '';
}

エラーコード NotBlank。デフォルトメッセージ: must not be blank。対応する型: String。パラメータ: message、groups。

サイズ

@Size

文字列の長さ、またはリスト、セット、マップの要素数を制限します。両端の値を含みます。null は通り、Size(min: 1) は ' ' を拒否しません(@NotBlank を使います)。

@Introspected()
class Signup {
  // A display name of 2 to 20 characters.
  @Size(min: 2, max: 20)
  String name = '';

  // At most 5 tags.
  @Size(max: 5)
  List<String> tags = [];
}

エラーコード Size。フィールドエラーの引数: [field, max, min]。Flutter アプリでは、Flutter 独自の Size クラスがあるため SizeConstraint という名前でエクスポートされます。

数値

数値の制約は int、double、BigInt、数値の文字列を検証します。値は浮動小数点の丸めなしに正確に比較されます。数値でない文字列は失敗し、double.nan も失敗します。null は通ります。

@Min

value 以上の数値を求めます。

@Introspected()
class Signup {
  // Only adults may sign up.
  @Min(18)
  int age = 0;
}

エラーコード Min。フィールドエラーの引数: [field, value]。

@Max

value 以下の数値を求めます。

@Introspected()
class Order {
  // No more than 100 copies in one order.
  @Max(100)
  int quantity = 1;
}

エラーコード Max。フィールドエラーの引数: [field, value]。

@DecimalMin

小数の下限より大きい数値、inclusive のときは下限と等しい数値も求めます。下限に小数があるときや、下限そのものを除外したいときに @Min の代わりに使います。下限は文字列なので正確です。

@Introspected()
class Product {
  // Nothing is free: at least one cent.
  @DecimalMin('0.01')
  double price = 1;
}

エラーコード DecimalMin。フィールドエラーの引数: [field, inclusive, value]。

@DecimalMax

小数の上限より小さい数値、inclusive のときは上限と等しい数値も求めます。

@Introspected()
class Discount {
  // A discount below 100 percent.
  @DecimalMax('100', inclusive: false)
  double percent = 0;
}

エラーコード DecimalMax。フィールドエラーの引数: [field, inclusive, value]。

@Positive

0 より大きい数値を求めます。

@Introspected()
class Product {
  // A price must be above zero.
  @Positive()
  double price = 1;
}

エラーコード Positive。デフォルトメッセージ: must be greater than 0。パラメータ: message、groups。

@PositiveOrZero

0 以上の数値を求めます。

@Introspected()
class Account {
  // A balance may be empty, not overdrawn.
  @PositiveOrZero()
  int balance = 0;
}

エラーコード PositiveOrZero。デフォルトメッセージ: must be greater than or equal to 0。パラメータ: message、groups。

@Negative

0 より小さい数値を求めます。

@Introspected()
class Refund {
  // A refund is booked as a negative amount.
  @Negative()
  int amount = -1;
}

エラーコード Negative。デフォルトメッセージ: must be less than 0。パラメータ: message、groups。

@NegativeOrZero

0 以下の数値を求めます。

@Introspected()
class Adjustment {
  // A correction may lower the stock or leave it as it is.
  @NegativeOrZero()
  int delta = 0;
}

エラーコード NegativeOrZero。デフォルトメッセージ: must be less than or equal to 0。パラメータ: message、groups。

@Digits

数値の小数点の前と後の桁数を制限します。数値と BigInt は末尾のゼロを除いて数えます(1.50 の小数部は 1 桁)。数値の文字列は書かれたとおりに数えます('1.50' は 2 桁)。

@Introspected()
class Invoice {
  // Up to 999999.99, as in a DECIMAL(8, 2) column.
  @Digits(integer: 6, fraction: 2)
  double total = 0;
}

エラーコード Digits。フィールドエラーの引数: [field, fraction, integer]。

テキストの形式

@Matches

文字列全体が正規表現に一致することを求めます。Java の Matcher.matches() と同じです。^ と $ は不要です。デフォルトメッセージには正規表現がそのまま表示されるので、ユーザーにわかる message を指定してください。

@Introspected()
class Address {
  // A five-digit postal code.
  @Matches(r'\d{5}', message: 'must be 5 digits')
  String? zip;

  // Letters in any case.
  @Matches('[a-z]+', flags: [PatternFlag.caseInsensitive])
  String code = 'abc';
}

エラーコード Pattern(Jakarta の名前。Pattern は Dart のコア型です)。対応する型: String。フィールドエラーの引数: [field, flags, regexp]。

PatternFlag の値:

@Email

文字列がメールアドレスの形をしていることを求めます。形だけを確認し、アドレスが実在するかは確認しません。localhost のようにドットのないドメインも通ります。null と空文字列は通ります。アドレスを必須にするには @NotBlank() を加えます。

@Introspected()
class Signup {
  // Every user needs an address.
  @NotNull()
  @Email()
  String? email;

  // A work address must be in the company domain.
  @Email(regexp: r'.+@example\.com')
  String? work;
}

エラーコード Email。対応する型: String。フィールドエラーの引数: [field, flags, regexp]。

真偽値

@AssertTrue

bool が true であることを求めます。null は通ります。

@Introspected()
class Signup {
  // The signup is refused until the terms are accepted.
  @AssertTrue(message: 'terms must be accepted')
  bool acceptedTerms = false;
}

エラーコード AssertTrue。デフォルトメッセージ: must be true。対応する型: bool。パラメータ: message、groups。

@AssertFalse

bool が false であることを求めます。null は通ります。

@Introspected()
class Account {
  // A new account cannot start locked.
  @AssertFalse()
  bool locked = false;
}

エラーコード AssertFalse。デフォルトメッセージ: must be false。対応する型: bool。パラメータ: message、groups。

日付

日付の制約は DateTime の値を検証します。「現在」はバリデータの ClockProvider から取得するので、テストで固定できます。

時刻のない DateTime(DateTime(2026, 5, 1) や DateTime.parse('2026-05-01') の結果)は日付として扱われ、Java の LocalDate と同じく日単位で比較されます。今日は過去でも未来でもありません。それ以外の値は正確な時点と比較されます。

@Past

現在より前の DateTime を求めます。

@Introspected()
class Person {
  // A birthday cannot be today or later.
  @Past()
  DateTime? birthday;
}

エラーコード Past。デフォルトメッセージ: must be a past date。パラメータ: message、groups。

@PastOrPresent

現在より前、または現在(日付なら今日)の DateTime を求めます。

@Introspected()
class Payment {
  // A payment can be booked today, not tomorrow.
  @PastOrPresent()
  DateTime? paidOn;
}

エラーコード PastOrPresent。デフォルトメッセージ: must be a date in the past or in the present。パラメータ: message、groups。

@FutureDate

現在より後の DateTime を求めます。

@Introspected()
class Booking {
  // A booking starts tomorrow at the earliest.
  @FutureDate()
  DateTime? startsOn;
}

エラーコード Future(Jakarta の名前。Future は Dart のコア型です)。デフォルトメッセージ: must be a future date。パラメータ: message、groups。

@FutureOrPresent

現在より後、または現在(日付なら今日)の DateTime を求めます。

@Introspected()
class Coupon {
  // A coupon that expired yesterday cannot be saved.
  @FutureOrPresent()
  DateTime? validUntil;
}

エラーコード FutureOrPresent。デフォルトメッセージ: must be a date in the present or in the future。パラメータ: message、groups。

テストで「現在」を固定するには、バリデータに ClockProvider を渡します。

// Tests run on a fixed date.
final class FixedClock implements ClockProvider {
  const FixedClock(this.time);
  final DateTime time;

  @override
  DateTime now() => time;
}

final validator = BeanValidator(
  introspector: introspector,
  clockProvider: FixedClock(DateTime.utc(2026, 1, 1)),
);

ネストしたオブジェクトとコレクション

@Valid

値の内部の制約を検証するようバリデータに指示します。ネストしたオブジェクト、リスト・セット・マップ内のオブジェクト、メソッド引数などです。これがないと、プロパティの内部の制約は検証されません。

@Introspected()
class Order {
  // An order is only valid with a valid address and valid items.
  @Valid()
  Address address = Address();

  @Valid()
  List<Item> items = [];
}

リスト要素内のエラーは items[0].sku、セット内は items[].sku、マップの値の中は byKey[key].sku として報告されます。null の値はスキップされます。@Valid() にパラメータはありません。

@Each

リストやセットのすべての要素、またはマップのすべての値を、制約のリストで検証します。Jakarta では型引数に書きます(List<@NotBlank String>)が、Dart ではそこにアノテーションを書けません。

@Introspected()
class Survey {
  // Short, non-blank answers.
  @Each([NotBlank(), Size(max: 20)])
  List<String> answers = [];

  // No negative scores.
  @Each([Min(0)])
  Map<String, int> scores = {};
}

null のコレクションはスキップされます。コレクションでもマップでもない値は ConstraintDeclarationException を投げます。リスト要素は answers[1].<list element>(フィールドエラーは answers[1])、マップの値は scores[math].<map value> として報告されます。

@EachKey

マップのすべてのキーを制約のリストで検証します。

@Introspected()
class Survey {
  // Subject names of at most 10 characters.
  @EachKey([Size(max: 10)])
  Map<String, int> scores = {};
}

キーは scores<K>[key].<map key>(フィールドエラーは scores[key])として報告されます。

グループ

グループはただの型で、通常は空の abstract final class です。1 つのクラスに状況ごとのルールを持たせられます。groups のない制約は Default に属します。グループを指定せずに検証すると Default だけが検証されます。通常のルールとあるグループの両方を検証するには、両方を並べます。

abstract final class OnUpdate {}

@Introspected()
class UserForm {
  // Set by the server on create, required on update.
  @NotNull(groups: [OnUpdate])
  int? id;

  @NotBlank()
  String name = '';
}

// An update checks the ordinary rules and the update rules.
validator.validateObject(form, groups: [Default, OnUpdate]);

@GroupSequence

クラスのグループを段階的に検証します。グループは順に検証され、違反のあったグループで検証が止まります。一部のルールが重い場合や、単純なルールが失敗している間は意味がない場合に使います。クラス自身が通常の制約を表し、リストに含める必要があります。Default は含めてはいけません。

abstract final class Expensive {}

@Introspected()
@GroupSequence([Order, Expensive])
class Order {
  @NotBlank()
  String sku = '';

  // Only checked when the ordinary constraints of Order pass.
  @StockAvailable(groups: [Expensive]) // a custom constraint
  String warehouse = '';
}

それ自体を 1 つのグループとして使うシーケンスは、代わりに BeanValidator(groupSequences: {Complete: [Default, Strict]}) に渡します。Dart のグループ型は実行時に読めるアノテーションを持てないためです。誤ったシーケンス(循環、リスト内の Default、クラス自身の欠落)は GroupDefinitionException を投げます。

@ConvertGroup

@Valid() の隣に置きます。外側の検証がグループ from を実行するとき、ネストした値はグループ to で検証されます。

abstract final class DriverChecks {}

@Introspected()
class Car {
  // The ordinary check of a Car checks its driver's DriverChecks rules.
  @Valid()
  @ConvertGroup(to: DriverChecks) // from: Default
  Driver? driver;
}

@Valid() がないと宣言エラーになります。

独自の制約を書く

組み込みの制約でカバーできないルールには Constraint を継承します。name(エラーコード)、defaultMessage、isValid をオーバーライドします。クラスレベルの制約はオブジェクト全体を受け取ります。

// A class-level rule that compares two properties.
class PasswordsMatch extends Constraint {
  const PasswordsMatch({super.message, super.groups});

  @override
  String get name => 'PasswordsMatch';

  @override
  String get defaultMessage => 'passwords must match';

  @override
  bool isValid(Object? value) =>
      value is! SignupForm || value.password == value.confirm;

  // Report the error on the `confirm` field, so a form can show it there.
  @override
  bool isValidWithContext(Object? value, ConstraintValidatorContext context) {
    if (isValid(value)) return true;
    context
      ..disableDefaultConstraintViolation()
      ..buildConstraintViolationWithTemplate(
        context.defaultConstraintMessageTemplate,
      ).addPropertyNode('confirm').addConstraintViolation();
    return false;
  }
}

@Introspected()
@PasswordsMatch()
class SignupForm {
  String password = '';
  String confirm = '';
}

オーバーライドできる Constraint のメンバー:

Spring (Java) では

class Signup {
  @NotBlank @Size(min = 2, max = 20) private String name;
  @Pattern(regexp = "\\d{5}") private String zip;
  @Future private LocalDate startsOn;
  private List<@NotBlank String> answers;
}

重要な違い:

• クラス名: @MustBeNull は @Null、@Matches は @Pattern、@FutureDate は @Future に当たります。エラーコードは Jakarta の名前です。
• コンテナ要素の制約は、型引数へのアノテーションではなく @Each([...]) と @EachKey([...]) で書きます。
• 独自の制約は isValid メソッドを持つ 1 つのクラスです。Java ではアノテーションと別の ConstraintValidator クラスが必要です。
• @Matches は Dart の RegExp 構文を使います。フラグは Dart にあるオプションに限られます。
• 日付の制約は DateTime に対して働きます。午前 0 時ちょうどの DateTime は日付(LocalDate)として扱われます。
• グループ型に付ける @GroupSequence は BeanValidator(groupSequences: ...) に渡します。

関連項目

• バリデーションの概要
• Validator, Errors and DataBinder
• メソッドバリデーション
• Configuration