オブジェクトとコレクション
プロパティは、入れ子のオブジェクト、リスト、Map にできます。このページでは、同じ Map から読み取るプロパティ、未知のキー、プロパティが実行時に決まるスキーマ、再帰構造も扱います。
入れ子のオブジェクト
入れ子のオブジェクトは _object(name, validator) で追加します。バリデータは fromMap または from で構築し、入れ子の Map またはノードを読み取ります。
ObjectInputValidator<Address> addressValidator = Yavi.schema()
._string("street", c -> c.notBlank())
._string("city", c -> c.notBlank())
.fromMap(Address::new);
ObjectInputValidator<User> userValidator = Yavi.schema()
._string("email", c -> c.notBlank().email())
._object("address", addressValidator)
.fromMap(User::new);
入れ子の値の違反は、プロパティ名の下に位置づけられます。name()(address.street)と path() の両方です。入れ子のバリデータは複数のスキーマで再利用でき、Map 用に定義したバリデータは、外側のバリデータを readingWith(reader) で読み取る場合に JSON ツリーにも使えます。
リスト
_list(name, elementValidator) は、与えられたバリデータで各要素を検証します。要素の違反はそのインデックスの下に位置づけられます。
ObjectInputValidator<User> userValidator = Yavi.schema()
._string("email", c -> c.notBlank().email())
._list("roles", Yavi._string(c -> c.notBlank())) // roles[0]
._list("tags", Yavi._string(c -> c.notBlank()),
c -> c.notEmpty().lessThanOrEqual(10).unique()) // tags
.fromMap(User::new);
- 要素は他の値と同じように必須です。
List<@Nullable String>にはelementValidator.nullable()を与えます。 _listの制約は、すべての要素が有効な場合にだけ、検証済みの要素に対して検査され、プロパティ(roles)で報告されます。unique(key)は、識別子など要素のキーによって要素を一意にします。重複したキーはメッセージとparamsに含まれます。- 名前が空の要素バリデータは、要素のプロパティではなく要素自体の違反を報告します。
- オブジェクトを読み取るバリデータを伴う
_listはaddresses[0].streetを報告します。
次のプログラムは、空の street と空の要素を、違反の位置を示す名前 address.street と roles[1] で報告します。
Map
_map(name, valueValidator) は Map の各値を検証します。キーはプロパティ名ではなくデータであるため、違反はキーの下に位置づけられます(scores.math)。
ObjectInputValidator<Exam> examValidator = Yavi.schema()
._string("student")
._map("scores", Yavi._integer(c -> c.greaterThanOrEqual(0).lessThanOrEqual(100)),
c -> c.notEmpty())
.fromMap(Exam::new);
文字列でないキーは object.type で報告されます。_map の制約は検証済みの値に対して検査され、プロパティで報告されます。
埋め込みオブジェクト
_embedded(validator) は、プロパティと同じ Map を読み取ります。JOIN の行にある複数のテーブルの列からオブジェクトを構築します。
ObjectInputValidator<UserName> userNameValidator = Yavi.schema()
._string("first_name", c -> c.notBlank())
._string("last_name", c -> c.notBlank())
.fromMap(UserName::new);
ObjectInputValidator<Department> departmentValidator = Yavi.schema()
._string("dept_name", c -> c.notBlank())
._string("dept_code", c -> c.notBlank())
.fromMap(Department::new);
ObjectInputValidator<Employee> employeeValidator = Yavi.schema()
._integer("id")
._embedded(userNameValidator) // first_name, last_name
._embedded(departmentValidator).nullable() // null if dept_name and dept_code have no value
.fromMap(Employee::new);
- 埋め込みバリデータのプロパティは、埋め込む側のプロパティです。記述され、
rejectingUnknownProperties()から未知とは見なされず、同じ名前を二度定義するとバリデータの構築時に拒否されます。 optional()、nullable()、defaultValue(...)を伴う埋め込みバリデータは、どのプロパティにも値がない場合にnullを受け取ります。- 埋め込みは、16 個を超えるキーを読み取る方法でもあります。
- ラムダも埋め込めます。読み取るプロパティが不明なため、そのバリデータは未知のプロパティを拒否できず、rest も読めません。
未知のプロパティ
どのプロパティにも定義されていないキーは無視されます。rejectingUnknownProperties() はそれを object.unknownProperty で報告し、JSON Schema に additionalProperties: false を書きます。
ObjectInputValidator<Signup> signupValidator = Yavi.schema()
._string("email", c -> c.notBlank().email())
.fromMap(Signup::new)
.rejectingUnknownProperties();
この設定はその Map にだけ適用され、入れ子の Map には適用されません。任意のプロパティの綴り間違いを見つけられます。チェックボックスのように隠しフィールドを追加するフォームは、そのキーのプロパティか rest を必要とします。
rest プロパティ
_rest(valueValidator) は、どのプロパティにも定義されていないキーを検証し、Map としてコンストラクタに渡します。_rest() は値をそのまま受け取ります。
record Item(String name, Map<String, String> attrs) {}
ObjectInputValidator<Item> itemValidator = Yavi.schema()
._string("name", c -> c.notBlank())
._rest(Yavi._string(c -> c.notBlank()))
.fromMap(Item::new);
_restはスキーマの最後のプロパティであり、_restを持つスキーマにrejectingUnknownProperties()はありません。未知のキーが存在しないためです。- 他のキーがなければ rest は空の Map であり、
nullにはなりません。そのためrecover(...)だけを取り、_rest().nullable()はコンパイルできません。 - rest の違反はそのキーの下に位置づけられます。
実行時に決まるスキーマ
Yavi.dynamicSchema() は、設定やデータベースから来るプロパティ、たとえばアンケートの質問やカスタムフィールドを記述します。そのバリデータは、検証済みの値を名前ごとにまとめた Map を生成します。
record Question(String id, String title, boolean required, int maxLength) {}
DynamicSchema<String> schema = Yavi.dynamicSchema();
for (Question question : survey.questions()) {
StringValidator<String> answer = Yavi._string(c -> c.notBlank().lessThanOrEqual(question.maxLength()));
schema = question.required() ? schema.property(question.id(), answer).label(question.title())
: schema.property(question.id(), answer.defaultValue("")).label(question.title());
}
ObjectInputValidator<Map<String, String>> answersValidator = schema.build();
answersValidator.validate(Map.of("q1", "yavi")); // {q1=yavi}
スキーマは不変です。property(name, validator) は新しいスキーマを返します。バリデータはプロパティの名前の下で使われ、値はバリデータが null を受け入れない限り必須です。修飾は label、required(message)、typeMessage、presence() で、Yavi.schema() と同じ段階的な型を持ちます。rest(valueValidator) はどのプロパティにも定義されていないキーを検証し、Map に追加します。結果は rejectingUnknownProperties()、readingParameters()、description() を持ち、別のスキーマのプロパティにもできます。
再帰構造
ValueValidator.recursive(self -> ...) は、自身への参照からバリデータを構築します。自身を含む構造のためです。
record Comment(String body, List<Comment> replies) {}
ObjectInputValidator<Comment> commentValidator = ValueValidator.recursive(self -> Yavi.schema()
._string("body", c -> c.notBlank())
._list("replies", self).defaultValue(List.of())
.fromMap(Comment::new));
// a violation: replies[0].replies[0].body
ValueValidator.lazy(() -> validator) は、まだ構築されていないバリデータを参照します。互いに参照するバリデータのためです。$defs で記述を書く場合は、参照に名前を与えます。lazy("comment", ...) または recursive("comment", ...) です。
再帰構造の深さは入力の深さです。YAVI は制限を設けないため、信頼できない文書にはパーサの最大深さなど、独自の制限が必要です。