Describing a Schema
A validator describes the input it expects. This page shows the description tree, the JSON Schema generated from it, and what cannot be described.
Descriptions
description() returns a read-only ValueDescription: a tree of objects with properties, lists, maps, alternatives and values with their constraints. A tool can walk it without the classes the validator was built from.
ValueDescription description = userValidator.description();
ValueDescription.Properties object = (ValueDescription.Properties) description;
for (ValueDescription.Property property : object.properties()) {
System.out.println(property.name() + ": " + property.value());
}
A constraint is described by its message key and arguments, for example container.lessThanOrEqual with [14]. A property that is withheld is marked as such. The description carries the name of the property and, for a nested value, its structure.
The description is immutable and is built from the schema, not from an input. A schema that reads a map, a JSON tree and request parameters has one description, because the properties are the same.
JSON Schema
JsonSchema is a consumer of the description. It needs no JSON library:
Map<String, Object> schema = JsonSchema.of(userValidator.description());
String json = JsonSchema.toJson(userValidator.description());
The output follows 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"]
}
- A property is
requiredunless it accepts an absent key. A property withpresence()is neverrequired. - A property that accepts
nulllistsnullin its type, and adefaultValue(...)orrecover(...)is written asdefault. - A required value whose constraints accept
nullis described with the constraintobject.notNull. - A validator that rejects unknown properties is written with
additionalProperties: false, and one that reads the rest with the schema of its values. - The constraints of a list or a map are written as
minItems,maxItems,uniqueItems,minPropertiesandmaxProperties. - A withheld property is
writeOnly. - The alternatives of a discriminated union are an
AnyOfwhosediscriminatoris the name of the key that selects one.
The generated schema describes the input of the validator. It is not a schema of the object that the validator creates, so it has the key and type of a property before map.
Recursive and shared definitions
A recursive structure is described with a ValueDescription.Reference where it contains itself. It is written as $ref, to # for the described validator itself, and otherwise to $defs under the name given to ValueValidator.lazy(name, ...) or ValueValidator.recursive(name, ...):
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"}
A reference to the described validator itself is written as #. A name given to lazy or recursive is used for a definition that is referred to from more than one place.
Limitations
- A lambda and the result of
ValueValidator.composeare unknown. Describe them withdescribedAs(description). - Conditional constraints and
constraintOnTargetrules are not described. They are not part of the shape of the input, or they span several properties. - A constraint without a JSON Schema keyword is omitted. For example,
unique(key)has no keyword and is not written;unique()is written asuniqueItems. - A bean
Validatorbuilt withValidatorBuilderis not described. UseYavi.schema()for the input and the classic validator for the object. - A
renamingview and anincludingorexcludingview are not part of the description of the validator. They write an object; the description still describes the input. - A description reflects what the validator checks. It does not replace validation: a client that trusts the schema still needs the validator on the server.