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 79d3ab6d95 docs: document @Schema summary field for LLM consumption
(TODO-6)
79d3ab6d95 is described below
commit 79d3ab6d95ec5bbb373e62aa6980e347cb673461
Author: James Bognar <[email protected]>
AuthorDate: Fri May 15 14:12:44 2026 -0400
docs: document @Schema summary field for LLM consumption (TODO-6)
Co-authored-by: Cursor <[email protected]>
---
pages/release-notes/9.5.0.md | 26 +++++++++++++++++++
pages/topics/02.25.JsonSchemaDetails.md | 40 ++++++++++++++++++++++++++++++
pages/topics/04.04.JuneauBeanJsonSchema.md | 21 ++++++++++++++++
3 files changed, 87 insertions(+)
diff --git a/pages/release-notes/9.5.0.md b/pages/release-notes/9.5.0.md
index e57c95e97f..ee1731baa4 100644
--- a/pages/release-notes/9.5.0.md
+++ b/pages/release-notes/9.5.0.md
@@ -10,6 +10,32 @@ Juneau 9.5.0 is a minor release with native TOML and YAML
support, BSON (Binary
### juneau-marshall
+#### Typed `JsonSchema` bean generation bridge (TODO-8)
+
+- Added `JsonSchemaBeanGenerator` in `juneau-bean-jsonschema` to generate
typed `JsonSchema` beans from Java types via `JsonSchemaGenerator`.
+- Added static convenience factories on `JsonSchema`: `JsonSchema.of(Type)`
and `JsonSchema.of(Class<?>)`.
+- 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.
+
+#### 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.
+- `summary` flows through `SchemaAnnotation.asMap()` and `JsonSchemaGenerator`
into the generated JSON Schema output under the key `"summary"`.
+- Added a paired `summary` field on companion annotations that already expose
`description`: `@Marshalled`, `@BeanProp`, `@Response`, `@Header`, `@Query`,
`@Path`, `@FormData`, `@Content`.
+- Added `JsonSchema.getSummary()` / `setSummary(String)` (and fluent overrides
on `JsonSchemaProperty` and `JsonSchemaRef`), so the typed bean and the
`JsonSchemaBeanGenerator` bridge surface the new field automatically.
+- Added Swagger / OpenAPI propagation: `summary` from `@Schema` is now copied
into the generated Swagger Schema Object alongside `description`.
+- Example:
+ ```java
+ @Schema(
+ summary="A pet available for adoption",
+ description={
+ "Represents a pet in the store's inventory.",
+ "Includes details such as name, species, breed, age, and adoption
status."
+ }
+ )
+ public class Pet { ... }
+ ```
+
### juneau-commons
### juneau-config
diff --git a/pages/topics/02.25.JsonSchemaDetails.md
b/pages/topics/02.25.JsonSchemaDetails.md
index cb89867315..ac3188a5a1 100644
--- a/pages/topics/02.25.JsonSchemaDetails.md
+++ b/pages/topics/02.25.JsonSchemaDetails.md
@@ -9,6 +9,18 @@ This class shares the same properties as `JsonSerializer`.
For convenience the <a
href="/site/apidocs/org/apache/juneau/json/JsonSerializer.html#getSchemaSerializer()"
target="_blank">JsonSerializer.getSchemaSerializer()</a> method has been added
for creating instances of schema serializers from the regular serializer
instance.
+When you want a typed schema DTO instead of raw map output, use
+<a
href="/site/apidocs/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator.html"
target="_blank">JsonSchemaBeanGenerator</a>
+from `juneau-bean-jsonschema`:
+
+```java
+import org.apache.juneau.bean.jsonschema.*;
+
+JsonSchema schema = JsonSchemaBeanGenerator.DEFAULT.generate(Person.class);
+// Equivalent convenience:
+JsonSchema schema2 = JsonSchema.of(Person.class);
+```
+
##### Sample Beans
```java
@@ -95,3 +107,31 @@ jsonSchema = serializer.serialize(Person.class);
}
}
```
+
+##### AI-friendly `summary` (since 9.5.0)
+
+The `@Schema` annotation supports a `summary` field (alias `su`) for short,
single-line
+descriptions intended for AI / LLM consumption, compact docs, and tooltips.
Unlike
+`description`, which can be multi-line and detailed, `summary` should be a
single
+sentence or phrase that captures the essential meaning.
+
+```java
+@Schema(
+ summary="A pet available for adoption",
+ description={
+ "Represents a pet in the store's inventory.",
+ "Includes details such as name, species, breed, age, and adoption
status."
+ }
+)
+public class Pet {
+
+ @Schema(summary="The pet's display name")
+ public String name;
+}
+```
+
+The `summary` value is emitted under the JSON Schema key `"summary"` and is
also
+propagated through `JsonSchemaBeanGenerator` (accessible via
+`JsonSchema.getSummary()`) and into generated Swagger / OpenAPI documents. The
+companion annotations `@Marshalled`, `@BeanProp`, `@Response`, `@Header`,
`@Query`,
+`@Path`, `@FormData`, and `@Content` expose a matching `summary` field.
diff --git a/pages/topics/04.04.JuneauBeanJsonSchema.md
b/pages/topics/04.04.JuneauBeanJsonSchema.md
index 9191740173..2662e4741b 100644
--- a/pages/topics/04.04.JuneauBeanJsonSchema.md
+++ b/pages/topics/04.04.JuneauBeanJsonSchema.md
@@ -18,6 +18,7 @@ This module contains predefined POJOs for representing and
manipulating JSON Sch
- **Fluent API:** Method chaining for intuitive schema construction
- **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
## Basic Usage
@@ -51,6 +52,25 @@ JsonSchema schema = new JsonSchema()
String json = JsonSerializer.DEFAULT_SORTED.serialize(schema);
```
+### Generating Typed Schemas from Java Types
+
+If you already use `JsonSchemaGenerator` and want typed bean output, use
`JsonSchemaBeanGenerator`:
+
+```java
+import org.apache.juneau.bean.jsonschema.*;
+import org.apache.juneau.jsonschema.*;
+
+JsonSchemaBeanGenerator generator = JsonSchemaBeanGenerator.create()
+ .useBeanDefs()
+ .addDescriptionsTo(TypeCategory.ANY)
+ .build();
+
+JsonSchema schema = generator.generate(Person.class);
+
+// Convenience static factory methods on JsonSchema:
+JsonSchema schema2 = JsonSchema.of(Person.class);
+```
+
**Output:**
```json
{
@@ -396,6 +416,7 @@ schema.addDefinition("myDef", new JsonSchema());
**Metadata:**
- `setTitle(String)` - Human-readable title
- `setDescription(String)` - Detailed description
+- `setSummary(String)` - Short, single-line summary suitable for AI / LLM
consumption (since 9.5.0)
- `addExamples(Object...)` - Add example values
**Type Constraints:**
