This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch docs
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/docs by this push:
new 7dd0a8a4cb docs: schema validation mode for parsers and serializers
(TODO-12)
7dd0a8a4cb is described below
commit 7dd0a8a4cb141967df954b611cbb52c2487844be
Author: James Bognar <[email protected]>
AuthorDate: Mon May 18 10:02:07 2026 -0400
docs: schema validation mode for parsers and serializers (TODO-12)
Co-authored-by: Cursor <[email protected]>
---
pages/release-notes/9.5.0.md | 19 +++++++++++++++++
pages/topics/01.02.Marshalling.md | 31 +++++++++++++++++++++++++++
pages/topics/02.25.JsonSchemaDetails.md | 8 +++++++
pages/topics/04.04.JuneauBeanJsonSchema.md | 34 ++++++++++++++++++++++++++++++
4 files changed, 92 insertions(+)
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index ee1731baa4..e400e684a9 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -17,6 +17,25 @@ Juneau 9.5.0 is a minor release with native TOML and YAML
support, BSON (Binary
- Added `JsonSchema` bean support for `format`, `$comment`, and `deprecated`
so bean output preserves generator metadata.
- Added tests covering `JsonSchemaBeanGenerator` output parity with
`JsonSchemaGenerator` map output and round-trip conversion.
+#### Schema validation mode for parsers and serializers (TODO-12)
+
+- Added an opt-in `validateSchema` flag on `MarshallingContext` that validates
bean-property values against the constraints declared by `@Schema` annotations
during both parsing (value set on the bean) and serialization (value read from
the bean).
+- Backed by a new `JsonSchemaValidator` in `juneau-bean-jsonschema` that
implements JSON Schema Draft 2020-12 semantics on top of the typed `JsonSchema`
bean.
+- Added new commons-side SPI (`PropertyValidator` / `PropertyValidatorFactory`
/ `PropertyValidators`) so marshall and `juneau-bean-jsonschema` stay
decoupled. The factory is discovered via `ServiceLoader`; when
`juneau-bean-jsonschema` is absent, the flag becomes a silent no-op.
+- Added fluent enablers: `MarshallingContext.Builder.validateSchema()` /
`validateSchema(boolean)`, propagated through `MarshallingContextable.Builder`
and every parser/serializer/REST-client builder subclass so chains like
`JsonParser.create().validateSchema().build()` keep their concrete return type.
+- Added `@BeanConfig(validateSchema="true")` so the flag can be configured by
annotation (with `VarResolver.DEFAULT` interpolation).
+- Validation failures throw `SchemaValidationException`; parsers surface them
as `ParseException` and serializers as `SerializeException`.
+- Supported keywords (v1): `type`, `enum`, `const`, numeric (`minimum`,
`maximum`, `exclusiveMinimum`, `exclusiveMaximum`, `multipleOf`), string
(`minLength`, `maxLength`, `pattern`), array (`minItems`, `maxItems`,
`uniqueItems`, `items`), object (`minProperties`, `maxProperties`, `required`,
`properties`).
+- Example:
+ ```java
+ public class MyBean {
+ @Schema(minLength=2, maxLength=10) public String name;
+ @Schema(minimum="0", maximum="150") public int age;
+ }
+ ReaderParser p = JsonParser.create().validateSchema().build();
+ p.parse("{\"name\":\"a\"}", MyBean.class); // throws ParseException - too
short
+ ```
+
#### AI-friendly `summary` field on `@Schema` and related annotations (TODO-6)
- Added a `summary` field (alias `su`) to `@Schema`, designed to hold a short,
single-line description suitable for AI / LLM consumption, compact docs, and
tooltips. Complements (and does not replace) the existing multi-line
`description` field.
diff --git a/pages/topics/01.02.Marshalling.md
b/pages/topics/01.02.Marshalling.md
index 306a6e9e48..1c34b375ee 100644
--- a/pages/topics/01.02.Marshalling.md
+++ b/pages/topics/01.02.Marshalling.md
@@ -336,6 +336,37 @@ public void doGet(
:::
+#### Bean Property Schema Validation
+
+Since 9.5.0, parsers and serializers can also enforce JSON-Schema constraints
declared via
+<a href="/site/apidocs/org/apache/juneau/commons/annotation/Schema.html"
target="_blank">`@Schema`</a>
+on bean properties, independent of HTTP parts. Validation is opt-in via
+`MarshallingContext.Builder.validateSchema()` and is powered by
+<a
href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaValidator.html"
target="_blank">`JsonSchemaValidator`</a>
+in `juneau-bean-jsonschema`.
+
+```java
+public class MyBean {
+ @Schema(minLength=2, maxLength=10) public String name;
+ @Schema(minimum="0", maximum="150") public int age;
+}
+
+ReaderParser p = JsonParser.create().validateSchema().build();
+p.parse("{\"name\":\"a\",\"age\":42}", MyBean.class); // throws
ParseException - minLength
+```
+
+The flag flows through `@BeanConfig(validateSchema="true")` and every builder
subclass (parsers,
+serializers, REST clients). Failures surface as `ParseException` on the parse
side and
+`SerializeException` on the serialize side. When `juneau-bean-jsonschema` is
not on the classpath
+the flag becomes a silent no-op.
+
+:::info See Also
+
+- [JSON-Schema Support](/docs/topics/JsonSchemaDetails) for the
marshalling-side schema details.
+- [juneau-bean-jsonschema](/docs/topics/JuneauBeanJsonSchema) for the full
validator reference and supported keywords.
+
+:::
+
#### YAML Marshalling
The Marshalling API also supports YAML serialization and parsing, implemented
natively without any external
diff --git a/pages/topics/02.25.JsonSchemaDetails.md
b/pages/topics/02.25.JsonSchemaDetails.md
index ac3188a5a1..273f9b6dae 100644
--- a/pages/topics/02.25.JsonSchemaDetails.md
+++ b/pages/topics/02.25.JsonSchemaDetails.md
@@ -21,6 +21,14 @@ JsonSchema schema =
JsonSchemaBeanGenerator.DEFAULT.generate(Person.class);
JsonSchema schema2 = JsonSchema.of(Person.class);
```
+##### Schema Validation
+
+Since 9.5.0, parsers and serializers can also enforce `@Schema` constraints at
parse/serialize time by enabling
+`MarshallingContext.Builder.validateSchema()`. Validation is powered by
+<a
href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaValidator.html"
target="_blank">JsonSchemaValidator</a>
+in `juneau-bean-jsonschema`, which implements JSON Schema Draft 2020-12
semantics over the typed `JsonSchema` bean.
+See [juneau-bean-jsonschema](JuneauBeanJsonSchema) for details and supported
keywords.
+
##### Sample Beans
```java
diff --git a/pages/topics/04.04.JuneauBeanJsonSchema.md
b/pages/topics/04.04.JuneauBeanJsonSchema.md
index 2662e4741b..17c9adf113 100644
--- a/pages/topics/04.04.JuneauBeanJsonSchema.md
+++ b/pages/topics/04.04.JuneauBeanJsonSchema.md
@@ -19,6 +19,7 @@ This module contains predefined POJOs for representing and
manipulating JSON Sch
- **Type Safety:** Uses enums and typed collections
- **Format Agnostic:** Serialize to JSON, XML, HTML, or any other
Juneau-supported format
- **Generator Bridge:** `JsonSchemaBeanGenerator` converts
`JsonSchemaGenerator` output into typed `JsonSchema` beans
+- **Schema Validator:** `JsonSchemaValidator` validates values against a
`JsonSchema` bean using Draft 2020-12 semantics, and integrates with the
marshalling layer via `MarshallingContext.Builder.validateSchema()`
## Basic Usage
@@ -406,6 +407,39 @@ schema.addDefinition("myDef", new JsonSchema());
- <a href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaRef.html"
target="_blank">`JsonSchemaRef`</a> - Schema reference ($ref)
- <a
href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaArray.html"
target="_blank">`JsonSchemaArray`</a> - Array of schemas
- <a href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaMap.html"
target="_blank">`JsonSchemaMap`</a> - Map of schemas
+- <a
href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaValidator.html"
target="_blank">`JsonSchemaValidator`</a> - Validates values against a
`JsonSchema` bean using Draft 2020-12 semantics (since 9.5.0)
+
+## Schema Validation
+
+`JsonSchemaValidator` validates a runtime value against a `JsonSchema` bean.
It can be used standalone, or installed automatically by the marshalling layer
via `MarshallingContext.Builder.validateSchema()` so parsers and serializers
enforce `@Schema`-declared constraints on bean properties.
+
+Standalone usage:
+
+```java
+JsonSchema schema = new JsonSchema()
+ .setType(JsonType.STRING)
+ .setMinLength(2)
+ .setMaxLength(10)
+ .setPattern("^[a-z]+$");
+
+JsonSchemaValidator v = JsonSchemaValidator.of(schema);
+v.validate("hello"); // OK
+v.validate("Hi!"); // throws SchemaValidationException - pattern fails
+```
+
+Integration with marshalling (since 9.5.0):
+
+```java
+public class MyBean {
+ @Schema(minLength=2, maxLength=10)
+ public String name;
+}
+
+ReaderParser p = JsonParser.create().validateSchema().build();
+p.parse("{\"name\":\"a\"}", MyBean.class); // throws ParseException -
minLength
+```
+
+Supported keywords (v1): `type`, `enum`, `const`,
`minimum`/`maximum`/`exclusiveMinimum`/`exclusiveMaximum`/`multipleOf`,
`minLength`/`maxLength`/`pattern`, `minItems`/`maxItems`/`uniqueItems`/`items`,
`minProperties`/`maxProperties`/`required`/`properties`. Composition keywords
(`allOf`, `anyOf`, `oneOf`, `not`, `if`/`then`/`else`) and `$ref`/`$defs`
resolution are deferred.
### Key Methods
