スキーマの記述
バリデータは、期待する入力を記述します。このページでは記述ツリー、そこから生成される JSON Schema、記述できないものを示します。
記述
description() は読み取り専用の ValueDescription を返します。プロパティを持つオブジェクト、リスト、Map、代替案、制約を持つ値のツリーです。ツールは、バリデータの構築に使ったクラスなしでこれをたどれます。
ValueDescription description = userValidator.description();
ValueDescription.Properties object = (ValueDescription.Properties) description;
for (ValueDescription.Property property : object.properties()) {
System.out.println(property.name() + ": " + property.value());
}
制約はメッセージキーと引数で記述されます。たとえば container.lessThanOrEqual と [14] です。withheld() のプロパティはそのように印されます。記述はプロパティの名前と、入れ子の値の構造を持ちます。
記述は不変であり、入力ではなくスキーマから構築されます。Map、JSON ツリー、リクエストパラメータを読み取るスキーマの記述は一つです。プロパティが同じだからです。
JSON Schema
JsonSchema は記述の利用者です。JSON ライブラリを必要としません。
Map<String, Object> schema = JsonSchema.of(userValidator.description());
String json = JsonSchema.toJson(userValidator.description());
出力は JSON Schema draft 2020-12 に従います。
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"email": { "type": "string", "minLength": 1, "format": "email" },
"nickname": { "type": ["string", "null"], "minLength": 1 },
"age": { "type": ["integer", "null"], "minimum": 0, "default": 20 },
"tags": { "type": ["array", "null"], "items": { "type": "string", "minLength": 1 }, "default": [] }
},
"required": ["email"]
}
- プロパティは、キーの不在を受け入れる場合を除いて
requiredです。presence()のプロパティは決してrequiredになりません。 nullを受け入れるプロパティは型にnullを含め、defaultValue(...)やrecover(...)はdefaultとして書かれます。- 制約が
nullを受け入れる必須の値は、制約object.notNullで記述されます。 - 未知のプロパティを拒否するバリデータは
additionalProperties: falseとして、rest を読むバリデータはその値のスキーマとして書かれます。 - リストや Map の制約は
minItems、maxItems、uniqueItems、minProperties、maxPropertiesとして書かれます。 withheld()のプロパティはwriteOnlyです。- 判別ユニオンの代替案は
AnyOfであり、そのdiscriminatorは一つを選ぶキーの名前です。
生成されるスキーマはバリデータの入力を記述します。バリデータが生成するオブジェクトのスキーマではないため、map の前のプロパティのキーと型を持ちます。
再帰的な定義と共有される定義
再帰構造は、自身を含む場所で ValueDescription.Reference として記述されます。$ref として書かれ、記述対象のバリデータ自身には #、それ以外は ValueValidator.lazy(name, ...) または ValueValidator.recursive(name, ...) に与えた名前の $defs になります。
ObjectInputValidator<Comment> commentValidator = ValueValidator.recursive("comment", self -> Yavi.schema()
._string("body", c -> c.notBlank())
._list("replies", self).defaultValue(List.of())
.fromMap(Comment::new));
JsonSchema.toJson(commentValidator.description());
// {"$defs":{"comment":{...}},"$ref":"#/$defs/comment"}
記述対象のバリデータ自身への参照は # として書かれます。lazy や recursive に与えた名前は、複数の場所から参照される定義に使われます。
制限
- ラムダと
ValueValidator.composeの結果は不明です。describedAs(description)で記述します。 - 条件付きの制約と
constraintOnTargetの規則は記述されません。入力の形の一部ではないか、複数のプロパティにまたがるためです。 - JSON Schema のキーワードを持たない制約は省略されます。たとえば
unique(key)にはキーワードがなく、書かれません。unique()はuniqueItemsとして書かれます。 ValidatorBuilderで構築した bean のValidatorは記述されません。入力にはYavi.schema()を、オブジェクトには従来のバリデータを使います。renamingビューとincludingやexcludingのビューは、バリデータの記述の一部ではありません。それらはオブジェクトを書き出し、記述は入力を記述したままです。- 記述はバリデータが検査する内容を反映します。検証の代わりにはなりません。スキーマを信頼するクライアントでも、サーバーではバリデータが必要です。