省略と既定値
Yavi.schema() のプロパティは必須です。このページでは、キーの不在や null を受け入れる修飾、既定値やフォールバックを生成する修飾、キーを再び必須にする修飾を説明します。
キーの不在と明示的な null
スキーマが Map、リクエストパラメータ、JSON ツリーを読み取る場合、キーの不在は null と同じように検証されます。必須のプロパティでは次のようになります。
| 入力 | 違反 |
|---|---|
| キーが存在しない | object.required: "name" is required |
値が明示的に null | object.notNull: "name" must not be null、または null を拒否する制約の違反 |
null を受け入れるプロパティは、キーの不在も受け入れます。キーの不在が「変更しない」、null が「消去する」を意味する部分更新は、両者を区別する presence() で書きます。
null の受け入れ
nullable()、optional()、defaultValue(...) は最後に追加したプロパティに適用されます。
record User(String email, @Nullable String nickname, Optional<String> bio, Integer age) {}
ObjectInputValidator<User> userValidator = Yavi.schema()
._string("email", c -> c.notBlank().email())
._string("nickname", c -> c.lessThanOrEqual(20)).nullable()
._string("bio", c -> c.lessThanOrEqual(500)).optional()
._integer("age", c -> c.greaterThanOrEqual(0)).defaultValue(20)
.fromMap(User::new);
nullable()は@Nullable Stringを生成し、nullを生成する唯一の修飾です。optional()はOptional<String>を生成します。キーの不在またはnullに対してOptional.empty()です。defaultValue(20)は、キーの不在またはnullに対して既定値を生成します。
次のプログラムは name だけを送るため、nickname が null、bio が Optional.empty()、age が既定値の User を出力し、続けて name を省略して age を負にした入力の違反を出力します。
fromMap に渡す関数は、生成される型を受け入れなければなりません。NullAway や Kotlin を使う場合、nullable() のプロパティには @Nullable の引数(Kotlin では String?)が必要で、optional() には Optional<String> が必要です。
効果のない修飾を含む連鎖はコンパイルできません。.nullable().optional()、.defaultValue(1).nullable()、.defaultValue(1).recover(2) です。既に null を受け入れるバリデータで追加したプロパティ、たとえば _integer(Yavi._integer("page", c -> c.positive()).defaultValue(1)) は、null を受け入れる二つ目の修飾を取りません。
notNull() は、null の違反に別のメッセージを与える方法として引き続き使えます。isNull() には nullable() が必要です。._string("id", c -> c.isNull()).nullable() は null だけを受け入れますが、nullable() がないと null が欠落した値として拒否されるため、どの値も有効になりません。
Presence
presence() はプロパティを Presence として読み取ります。Present(value)、PresentNull、Absent のいずれかです。PATCH リクエストや JSON Merge Patch のように、キーの不在が値を変更せず、null が値を消去する場面のための修飾です。
record ProfilePatch(Presence<String> nickname, Presence<@Nullable String> bio) {}
ObjectInputValidator<ProfilePatch> patchValidator = Yavi.schema()
._string("nickname", c -> c.lessThanOrEqual(50)).presence()
._string("bio", c -> c.lessThanOrEqual(500)).nullable().presence()
.fromMap(ProfilePatch::new);
ProfilePatch patch = patchValidator.validated(Map.of("bio", "Hello")); // nickname is Absent
patch.nickname().ifPresent(profile::setNickname); // not called
profile.setBio(patch.bio().orElse(profile.getBio())); // null if the key is null
- キーの不在は
Absentであり、検証されません。そのためプロパティが必須になることはありません。 - 存在するキーは
presence()がない場合と同じように検証されます。明示的なnullは、プロパティがnullable()でない限り違反です。nullable()の場合はPresentNullになります。 presence()は最後の修飾です。nullable()、defaultValue(...)、recover(...)はその前に書き、存在するキーの値に適用します。presence()は、キーから読み取らない_embeddedや_restのプロパティには使えません。optional()の後にも使えません。OptionalがPresenceで包まれてしまうためです。apply(f)では引数自体がPresenceです。単一値のバリデータではliftPresence()が組み合わせです。- リクエストパラメータでは、値が空のパラメータ(
bio=)は存在し、nullです。
既定値
defaultValue(value) は、キーの不在と null に対してその値を生成します。既定値は検証されません。それがプロパティの値になります。
._integer("page", c -> c.greaterThanOrEqual(1)).defaultValue(1)
._boolean("includeArchived").defaultValue(false)
._list("tags", Yavi._string(c -> c.notBlank())).defaultValue(List.of())
既定値はプロパティの型です。そのため null の既定値は nullable() で書きます。制約の値、リスト、Map、Optional のように決して null にならない値に対する defaultValue(null) は、スキーマの構築時に NullPointerException で拒否されます。
復旧
recover(fallback) はプロパティを決して失敗させません。null と不正な値に対してフォールバックを生成します。Map、リクエストパラメータ、JSON ツリーから読み取る場合、型を表さない値もフォールバックを生成します。recoverWith(violations -> ...) は違反からフォールバックを計算します。たとえばログを取るためです。null に対しては違反が渡されません。
._integer("size", c -> c.greaterThanOrEqual(1).lessThanOrEqual(100)).recover(20)
._integer("page", c -> c.greaterThanOrEqual(0)).recover(0)
optional() や nullable() の後の recover は不正な値を復旧します。recover(...) の後の optional()、nullable()、defaultValue(...) は null が生成するものを変えます。null の復旧値は .nullable().recover(null) と書きます。
キーの必須化と null の拒否
部分更新ではない契約では、二つの状態の一方だけを受け入れることがよくあります。required() と rejectingNull() は、値の型を変えずにどちらかを示します。
record Account(@Nullable Instant deletedAt, Optional<String> bio, int page) {}
ObjectInputValidator<Account> accountValidator = Yavi.schema()
._instant("deletedAt").nullable().required() // must be sent, as null if there is none
._string("bio").optional().rejectingNull() // may be omitted, a text if it is sent
._integer("page").defaultValue(1).rejectingNull() // 1 only if omitted
.fromMap(Account::new);
accountValidator.validate(Map.of()); // "deletedAt" is required
accountValidator.validate(Collections.singletonMap("deletedAt", null)); // deletedAt=null, bio=Optional.empty, page=1
これらは optional()、nullable()、defaultValue(...)、recover(...) の後に書きます。型付き引数(apply)には不在の状態がないため、null はこれらがない場合と同じように検証されます。
| プロパティ | キーの不在 | 明示的な null |
|---|---|---|
_string("x") | object.required | object.notNull |
.nullable()、.optional()、.defaultValue(...)、.recover(...) | 受け入れる | 受け入れる |
その後に .required() | object.required | 受け入れる |
その後に .rejectingNull() | 受け入れる | object.notNull |
.presence() | Absent | プロパティが検証する |
nullness と型の変更
検証済みの値の型が、null を取りうるかどうかを示します。
| 修飾 | 生成される型 |
|---|---|
| なし | String |
nullable() | @Nullable String |
optional() | Optional<String> |
defaultValue(v) | String |
recover(v) | String。null を許す値に対する recover(null) では @Nullable String |
presence() | Presence<String>。nullable() の後では Presence<@Nullable String> |
JSpecify を読む nullness チェッカー(NullAway、Kotlin)を使う場合、nullable() の引数を @Nullable でない引数に渡す fromMap(User::new) はコンパイルできません。これが 0.18 のモデルが加える検査です。nullable() の書き忘れは、実行時の NullPointerException ではなく、呼び出し側のコンパイルエラーになります。
動作のまとめ
- キーの不在は
nullと同じように検証され、欠落した値としてコンストラクタに渡されることはありません。 nullを受け入れる修飾が、生成するもの(Optional.empty()、null、既定値)を決めます。required()はキーの不在を拒否し、rejectingNull()は明示的なnullを拒否します。どちらも型を変えません。presence()は部分更新の二つの状態のためのもので、プロパティの最後の修飾です。- 効果のない修飾を含む連鎖はコンパイルできません。