YAVI とは

YAVI は、Java で Zod のように入力の記述と検証を行うためのライブラリです。コードで書いたスキーマが、パース済みの JSON や送信されたフォームなどの型なしの入力を読み取り、型付きのオブジェクトまたは違反の一覧を生成します。このページではそのモデル、それを補う従来のオブジェクト検証モデル、ライブラリが保証する内容を説明します。

二つの検証方法

データを検証する方法は二つあります。

  1. 入力を検証してオブジェクトを生成する。コンストラクタを実行する前に入力を検査し、有効な値だけでコンストラクタを呼びます。規則に反するオブジェクトは生成できません。これは Zod と Raoh のモデルであり、YAVI 0.18 の主要なモデルです。
  2. 既に存在するオブジェクトを検証する。オブジェクトを先に生成し、その後でフィールドを検査します。これは Bean Validation のモデルです。new Car(null, "D", 1) は成功し、別の呼び出しが違反を報告します。

Yavi.schema() と fromMap(f) は一つ目を実装します。プロパティ名で型なしの入力を読み取り、各値を検査し、検証済みの値を関数に渡します。ValidatorBuilder は、フレームワークやデシリアライザなど別のものが生成したオブジェクトに対して二つ目を実装します。

スキーマ優先にする理由

スキーマ優先のモデルには、オブジェクト検証にはない利点があります。

  • 不正なオブジェクトが存在しません。Car が負の seatCount を持つ瞬間がありません。
  • スキーマはクラスではなく入力を記述します。同じ記述で Map、JSON ツリー、リクエストパラメータを読み取り、オブジェクトを書き戻せます。
  • 既定ではプロパティの不在が違反になります。オブジェクト検証では、notNull() を書き忘れると null がそのまま通ります。
  • 検証済みの値の型が null を取りうるかどうかを示します。nullable() は型を @Nullable に変え、NullAway や Kotlin コンパイラなどの nullness チェッカーは、その値を非 null 引数に渡す関数を拒否します。
  • 入力はリフレクションもキャストも使わずに読み取るため、規則はスキーマを書いた場所で静的に検査できます。

そのため、0.18 の API を出発点にすることを勧めます。Yavi.schema() と apply(f) は型付き引数のバリデータを構築し、これは Yavi.arguments() の直接の後継です。fromMap(f) は型なし入力のバリデータを構築し、これが今回のリリースで加わった機能です。

Bean Validation との関係

YAVI は Bean Validation の制約を、アノテーションではなくメソッド呼び出しで扱います。たとえば @NotNull、@Size、@Min、@Max、@Email、@Pattern、@Digits には、制約 API に対応するものがあります。グループと条件付き検証は ValidatorBuilder で利用できます。

違いは意図的です。

  • メタデータ層がありません。制約は Java の式なので、リファクタリングツールとコンパイラが認識します。
  • ConstraintValidator の登録も Validation.buildDefaultValidatorFactory() もありません。
  • スキーマはアノテーション付きのオブジェクトだけでなく、生の入力を読み取れます。
  • 違反は名前、構造化されたパス、JSON Pointer、メッセージキーを持つため、API がそのまま返せます。

アノテーションと YAVI の制約の対応表は Bean Validation との比較 にあります。

YAVI が保証すること

  • validate(input) は Validated<T> を返します。生成されたオブジェクトを持つ Validated.Valid か、見つかったすべての違反を持つ Validated.Invalid です。
  • fromMap、apply、flatFromMap、flatApply に渡す関数は、すべての引数が有効な場合にだけ呼ばれます。
  • 修飾がない限りプロパティは必須であり、その修飾は検証済みの値の型に現れます。
  • 違反は name()、path()、pointer()、messageKey() を持つ安定した構造で報告されます。
  • バリデータは一度構築すると不変で、スレッドセーフです。
  • プロパティの読み取りにリフレクションを使わず、アノテーション処理も必要としません。

YAVI は何が有効かを決めません。書かれた制約を評価し、その結果を報告します。