Comparison with Zod
Zod is a schema and decoder for TypeScript: it validates untyped input and returns a typed value. YAVI 0.18 expresses the same model in Java: Yavi.schema() describes the properties of an input once, and the resulting validator reads that input from a map, a JSON tree or request parameters and creates an object only when every property is valid. This is the primary use case of 0.18.
The shape of a Zod program maps to YAVI as follows:
- A schema is described with
Yavi.schema()and closed withfromMap(f); the functionfis the constructor of an ordinary Java record or class. - The result type is the Java type that
freturns, and the compiler checks it. There is no type inference (z.infer) and no generated schema type. - The input is not one
unknownvalue but a map, a JSON tree, request parameters or typed arguments; the same schema reads every form, and the form is chosen when the validator is used. - Whether a property may be absent or
nullis part of the type:nullable()produces a@Nullablevalue andoptional()anOptional, which a nullness checker (NullAway, Kotlin) and the compiler enforce.
Basic
const User = z.object({
email: z.string().email(),
age: z.number().int().min(0),
nickname: z.string().optional(),
});
const result = User.safeParse(JSON.parse(input));
if (result.success) {
result.data; // { email: string; age: number; nickname?: string }
} else {
result.error.issues;
}
record User(String email, Integer age, Optional<String> nickname) {}
ObjectInputValidator<User> userValidator = Yavi.schema()
._string("email", c -> c.notBlank().email())
._integer("age", c -> c.greaterThanOrEqual(0))
._string("nickname").optional()
.fromMap(User::new);
Map<String, Object> map = objectMapper.readValue(input, new TypeReference<>() {});
switch (userValidator.validate(map)) {
case Validated.Valid<User>(User user) -> save(user);
case Validated.Invalid<User>(ConstraintViolations violations) -> report(violations);
}
The schema validates the input, and only then does User::new run. The properties are given to the constructor as arguments, so the result is an ordinary record and the compiler checks that the schema describes it.
Vocabulary
| Zod | YAVI |
|---|---|
schema (ZodType<Output, Input>) | ValueValidator<T, X> (input T, output X). Yavi.schema() describes the properties; fromMap(f) or apply(f) makes a validator of them |
z.object({...}) | Yavi.schema()._xxx(...).fromMap(f) (ObjectInputValidator<X>) |
schema.safeParse(input) | validator.validate(input) returns Validated<X> |
schema.parse(input) | validator.validated(input) throws ConstraintViolationsException |
result.success / result.data / result.error | Validated.Valid(value) / Validated.Invalid(errors), a sealed interface |
issue (code, path, message) | ConstraintViolation (messageKey(), path(), message()) |
z.infer<typeof schema> | the result type of the function given to fromMap / apply |
Schemas
| Zod | YAVI |
|---|---|
z.string(), z.number(), z.boolean(), z.date() ... as a property | _string(name, c -> ...), _integer, _long, _double, _bigDecimal, _boolean, _localDate, _instant ... |
| the same as a schema of its own | Yavi._string(c -> ...), Yavi._integer(c -> ...) ... |
z.enum([...]) | _enum(name, Role.class); _enum(Yavi._enum(name, Role.class).ignoringCase()) reads the name in any case |
z.object({...}) nested | _object(name, anotherObjectInputValidator) |
z.array(schema) | _list(name, elementValidator), validator.liftList() |
z.record(z.string(), schema) | _map(name, valueValidator), validator.liftMap() |
z.array(schema).nonempty().min(1).max(10) | _list(name, elementValidator, c -> c.notEmpty().greaterThanOrEqual(1).lessThanOrEqual(10)), Yavi._list(elementValidator, c -> ...) (also unique(), contains(...)) |
z.record(z.string(), schema) with a size | _map(name, valueValidator, c -> c.notEmpty()), Yavi._map(valueValidator, c -> ...) |
.optional() | .optional().rejectingNull() (produces Optional<X>) |
.nullable() | .nullable().required() (produces @Nullable X) |
.nullish() | .optional() or .nullable() |
.optional() with undefined told from a value in the result | .presence() (produces Presence<X>) |
.nullable().optional() / .nullish() with the two told apart in the result | .nullable().presence() |
.default(value) | .defaultValue(value).rejectingNull(); .defaultValue(value) also replaces null |
.catch(value) | .recover(value) (also for null and an absent key) |
.catch(ctx => ...) | .recoverWith(violations -> ...) |
z.union([a, b]) | ValueValidator.anyOf(a, b) |
z.discriminatedUnion("type", [...]) | DiscriminatedUnionValidator.<X>of("type").when("circle", a).when("square", b) |
z.lazy(() => schema), a getter that refers to the schema | ValueValidator.lazy(() -> validator), ValueValidator.recursive(self -> ...) |
z.number().multipleOf(n) | c.multipleOf(n) of the integral types, BigInteger and BigDecimal (not of Double and Float) |
z.email(), z.uuid(), z.ipv4(), z.ipv6(), z.ulid() | c.email(), c.uuid(), c.ipv4(), c.ipv6(), c.ulid() |
z.union([z.ipv4(), z.ipv6()]) | c.ip() |
z.url() | c.uri() (any scheme), c.url() (a protocol of java.net.URL) |
z.cuid(), z.cuid2() | c.pattern(regex) |
.refine(predicate) on a value | a constraint (c -> c.predicate(...)) |
.refine(predicate) on an object | .constraintOnTarget(predicate, name, violationMessage) |
.transform(f) | .map(f) |
z.string().trim().toLowerCase(), .toUpperCase(), .normalize() | _string(name, c -> c.trim().toLowerCase()...), c.toUpperCase(), c.toNormalForm(form), c.transform(f), written before the constraints |
z.preprocess(f, schema) | validator.preprocess(f) for a value of the same type |
.pipe(schema) | .andThen(validator) |
z.unknown() / z.any() | _object(name, Object.class) |
z.object({...}) (strips unknown keys) | the default of fromMap |
z.strictObject({...}) | .rejectingUnknownProperties() |
z.looseObject({...}) | ._rest() |
z.object({...}).catchall(schema) | ._rest(valueValidator) |
a.extend(b.shape), z.intersection(a, b) of objects | ._embedded(b), which gives the object of b to the function |
z.toJSONSchema(schema) | JsonSchema.of(validator.description()) |
The constraints are listed in Built-in Constraints; the combinators of a value are described in Defining a Schema.
Inputs
A Zod schema always takes unknown, which in practice is what JSON.parse returns. In Java the input has several forms, and the same properties are read from all of them. The schema is written once with fromMap(f), and the form of the input is chosen last:
| Input | Zod | YAVI | Input type |
|---|---|---|---|
| A parsed JSON document as a map | schema.safeParse(JSON.parse(input)) | validator | Map<String, Object> |
| A value of unknown type | schema.safeParse(input) | validator.untyped() | Object |
| The tree model of a JSON library | validator.readingWith(reader) | the node type, such as JsonNode | |
| Request parameters, a submitted form | z.coerce, zod-form-data | validator.readingParameters() | Map<String, String>, Map<String, List<String>>, Map<String, String[]> |
| Typed arguments | Yavi.schema()...apply(f) | the types of the arguments |
A map or a value of unknown type
fromMap(f) builds a validator of a Map<String, Object>. untyped() turns it, and any other validator that knows its input type, into a ValueValidator<Object, X>, which is the counterpart of a Zod schema:
ValueValidator<Object, User> any = userValidator.untyped(); // rejects anything but a map
ValueValidator<Object, Object> id = ValueValidator.anyOf(Yavi._string(c -> c.notBlank()).untyped(),
Yavi._integer(c -> c.positive()).untyped());
The input type must be known when the validator is built. fromMap and untyped() throw for a lambda or an _enum / _object property added without a type; give it with untyped(type), _enum(name, type) or _object(name, type). See Maps and Untyped Values.
The tree model of a JSON library
readingWith(reader) binds a validator to an InputReader, which tells how to read the nodes of a tree model. The tree is validated without being copied to a map. from(reader, f) builds such a validator from the schema:
ValueValidator<JsonNode, User> nodeValidator = userValidator.readingWith(JsonNodeReader.INSTANCE);
ValueValidator<JsonNode, User> same = Yavi.schema()
._string("email")
.from(JsonNodeReader.INSTANCE, User::new);
YAVI has no dependency on a JSON library; a reader is a small class written once per tree model. Jackson shows a reader.
Request parameters
Request parameters and a submitted form are a flat map of strings. readingParameters() reads it with the properties written as for a JSON document:
ValueValidator<Map<String, ?>, SearchForm> validator = Yavi.schema()
._integer("page", c -> c.greaterThanOrEqual(1)).defaultValue(1)
._boolean("includeArchived").defaultValue(false)
._list("tags", tagValidator).defaultValue(List.of())
._object("address", addressValidator).nullable()
.fromMap(SearchForm::new)
.readingParameters();
// page=2&includeArchived=true&tags=a&tags=b&address.city=Tokyo
validator.validate(parameters);
It does what Zod needs two things for:
- The values are strings that stand for the type of their property, which is
z.coercein Zod. The rules are in Strings. - The keys are paths (
address.city,items[0].name) and a key with several values is a list, which is whatzod-form-dataadds to Zod for aFormData. See Request Parameters and Forms.
An empty list cannot be sent, so a list that may be empty has defaultValue(List.of()).
Typed arguments
In Java the input is usually already bound to a type, so a YAVI validator is typed first (ValueValidator<String, Email>). apply(f) builds a validator of typed arguments from the schema that fromMap(f) builds a validator of a map from. Zod has no counterpart: its schemas check the type and the constraints together. See Typed Arguments.
Rules that differ
Absent and null
Like a Zod schema, a property is required unless it says otherwise, and saying otherwise changes its type: nullable() produces @Nullable X and optional() Optional<X>, as z.infer gives X | null and X | undefined. A nullness checker that reads JSpecify (NullAway, Kotlin) therefore rejects a function that takes a nullable() property as a value that is not null.
Zod tells undefined (optional()) from null (nullable()). In YAVI an absent key is validated like null, so optional(), nullable() and defaultValue(...) accept both. Only the violation differs for a required property: an absent key is reported with object.required and an explicit null with object.notNull, or with the violation of a constraint that rejects null such as notBlank().
The last modifier of a property keeps the two apart as Zod does. required() rejects an absent key although null is accepted, and rejectingNull() rejects an explicit null although the key may be absent. The type of the value does not change.
const Account = z.object({
deletedAt: z.iso.datetime().nullable(), // the key is required
middleName: z.string().optional(), // null is rejected
page: z.number().int().default(1), // null is rejected
});
record Account(@Nullable Instant deletedAt, Optional<String> middleName, int page) {}
ObjectInputValidator<Account> accountValidator = Yavi.schema()
._instant("deletedAt").nullable().required()
._string("middleName").optional().rejectingNull()
._integer("page").defaultValue(1).rejectingNull()
.fromMap(Account::new);
presence() gives the three states to the created object, for a partial update (PATCH). The property is a Presence<X>: Absent for an absent key, which is not validated, and otherwise what the property makes of the value, null included.
record ProfilePatch(Presence<String> nickname, Presence<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);
See Optional and Default Values.
Unknown keys
Both ignore unknown keys unless the object is strict. rejectingUnknownProperties() reports them with the message key object.unknownProperty, which catches a typo in an optional property; like z.strictObject, it applies to that object only.
The counterpart of .catchall(schema) and z.looseObject is an argument: the result is created by a function, so the extra keys are given to it as a map. _rest(valueValidator) validates their values and _rest() takes them as they are.
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);
Types
Both are exact by default: "30" is not a number. YAVI accepts the representation a JSON document has for the type of the property:
- a number whatever its Java type is, as long as the value is kept (
30Land30.0are anInteger,30.5is not), - the name of a constant for an enum,
- an ISO-8601 string for
LocalDate,Instantand the other temporal types,DurationandPeriod, - the string form of a
UUIDand aURI(_object("id", UUID.class)).
A mismatch is reported with object.type ("age" must be of type integer).
Strings
z.coerce is chosen per schema and converts with the JavaScript constructors (Number(input), Boolean(input)). In YAVI the coercion of strings belongs to the input, not to a property, so the schema does not change:
readingParameters()coerces the strings of request parameters.CoercibleInputReader#coercingStrings()decorates a reader of a tree model, for a tree whose scalars are all strings:validator.readingWith(JsonNodeReader.INSTANCE.coercingStrings())reads a JSON document whose numbers are sent as strings.
Both follow the same rules, which are stricter than z.coerce:
| Input | z.coerce | YAVI |
|---|---|---|
"" for a number | 0 | null, so optional() and defaultValue apply |
" 30 " for a number | 30 | object.type; 30 with trimming() |
" a " for a string | " a "; "a" with .trim() | " a "; "a" with trimming() or c.trim() |
"0x1e" for a number | 30 | object.type |
"false" for a boolean | true | false |
"on", "1" for a boolean | true | object.type; true with booleanWords(), like z.stringbool() |
30 for a string | "30" | object.type |
trimming() and booleanWords() are options of StringCoercion, given to readingParameters(coercion) or coercingStrings(coercion):
validator.readingParameters(StringCoercion.strict().trimming().booleanWords());
This reads a submitted form, whose checked checkbox sends on. An empty string is null for a string property too.
Unions
z.union and ValueValidator.anyOf try the alternatives in order and report one issue when none matches: invalid_union with errors, the issues of each alternative, and object.anyOf, a ConstraintViolation.NoAlternativeMatched with alternatives(), the violations of each alternative (alternatives of a ViolationDetail.NoAlternativeMatched). DiscriminatedUnionValidator applies only the alternative selected by the discriminator, like z.discriminatedUnion. An alternative does not have to define the discriminator as z.literal(...): the key is hidden from an alternative that does not define it. See Unions.
Errors
A ConstraintViolation has a message key instead of an issue code, and the message is formatted with a MessageFormatter, so it can be localized. path() is a list of PathSegment.Property and PathSegment.Index, name() is its flat form (address.street, tags[0]) and pointer() its JSON Pointer (/address/street, /tags/0).
| Zod | YAVI |
|---|---|
z.flattenError(error) | violations.messagesByName(), a map of the name to the messages; the messages of the root are under the empty name |
error.issues as JSON | violations.details(), a list of ViolationDetail (name, pointer, messageKey, message, params, and alternatives for object.anyOf) |
issue.minimum, issue.maximum, issue.format and so on | params of a detail, violation.params() ({"max": 150}); the violated value is not in it |
z.treeifyError has no counterpart: the keys of messagesByPointer() address the nested values instead. See Violations.
Codecs
z.codec(input, output, { decode, encode }) and z.encode(schema, value) are a validator that writes what it reads:
| Zod | YAVI |
|---|---|
z.codec(z.string(), z.custom<Email>(), { decode, encode }) | Yavi._string("email", c -> c.email()).map(Email::new, Email::value) (ReversibleValueValidator) |
z.encode(codec, value) | validator.reverse(value) |
z.encode(objectSchema, value) | Yavi.reversibleSchema()...fromMapReversible(f, accessor1, ...), then validator.toMap(value) |
A validator that does not know its reverse, such as map(f), is the counterpart of a transform, which Zod refuses to encode at run time. YAVI refuses it at compile time: it is not a ReversibleValueValidator, which a schema of Yavi.reversibleSchema() takes. See Writing an Object Back.
Not available
- Object schema operations that derive a schema:
pick,omit,partial.extendandmergeare_embedded, which keeps the object of the embedded validator. z.tupleandz.literalas a schema (use theequalTo/oneOfconstraints).- Asynchronous refinements and transforms.
- More than 16 properties in one schema; group them with
_embedded, or useObjectInputValidator.of(parts, mapper).