This is an automated email from the ASF dual-hosted git repository.
jamesbognar pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/juneau.git
The following commit(s) were added to refs/heads/master by this push:
new aeec23af21 feat(@Schema): add AI-friendly summary field for LLM
consumption (TODO-6)
aeec23af21 is described below
commit aeec23af210d89c31d6c88d6c699f523c69a9ac1
Author: James Bognar <[email protected]>
AuthorDate: Fri May 15 14:12:22 2026 -0400
feat(@Schema): add AI-friendly summary field for LLM consumption (TODO-6)
---
.../apache/juneau/bean/jsonschema/JsonSchema.java | 29 ++
.../juneau/bean/jsonschema/JsonSchemaProperty.java | 6 +
.../juneau/bean/jsonschema/JsonSchemaRef.java | 6 +
.../apache/juneau/commons/annotation/Schema.java | 62 ++++
.../org/apache/juneau/commons/bean/BeanProp.java | 13 +
.../juneau/commons/bean/BeanPropAnnotation.java | 20 ++
.../org/apache/juneau/annotation/Marshalled.java | 13 +
.../juneau/annotation/MarshalledAnnotation.java | 20 ++
.../apache/juneau/annotation/SchemaAnnotation.java | 42 +++
.../org/apache/juneau/http/annotation/Content.java | 13 +
.../apache/juneau/http/annotation/FormData.java | 13 +
.../org/apache/juneau/http/annotation/Header.java | 13 +
.../org/apache/juneau/http/annotation/Path.java | 13 +
.../org/apache/juneau/http/annotation/Query.java | 13 +
.../apache/juneau/http/annotation/Response.java | 13 +
.../juneau/http/annotation/ResponseAnnotation.java | 20 ++
.../rest/swagger/BasicSwaggerProviderSession.java | 1 +
.../jsonschema/JsonSchemaBeanGenerator_Test.java | 13 +
.../juneau/bean/jsonschema/JsonSchema_Test.java | 22 ++
.../juneau/jsonschema/JsonSchemaGeneratorTest.java | 44 +++
.../annotation/SchemaAnnotation_Test.java | 40 ++-
todo/FINISHED-6-ai-short-description.md | 278 ++++++++++++++++++
todo/TODO-6-ai-short-description.md | 320 ---------------------
todo/TODO-7-decouple-rest-common-from-marshall.md | 174 ++++++++---
todo/TODO.md | 4 +-
25 files changed, 848 insertions(+), 357 deletions(-)
diff --git
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java
index 2d8ca6a927..4cd9843cc4 100644
---
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java
+++
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java
@@ -319,6 +319,7 @@ public class JsonSchema {
private URI id; // Draft 04: id
(deprecated but kept for compatibility)
private URI schemaVersion;
private String title;
+ private String summary;
private String description;
private JsonType typeJsonType; // JsonType
representation of type
private JsonTypeArray typeJsonTypeArray; // JsonTypeArray
representation of type
@@ -1238,6 +1239,22 @@ public class JsonSchema {
@BeanProp("then")
public JsonSchema getThen() { return then_; }
+ /**
+ * Bean property getter: <property>summary</property>.
+ *
+ * <p>
+ * A short, concise summary of the schema's purpose, intended for
AI/LLM consumption, compact
+ * documentation, or any context where brevity is important. Unlike
{@link #getDescription()},
+ * which can be multi-line and detailed, this value should be a single
sentence or phrase.
+ *
+ * <p>
+ * This is a Juneau extension. It serializes as the JSON Schema keyword
<c>"summary"</c>.
+ *
+ * @return The value of the <property>summary</property> property, or
<jk>null</jk> if it is not set.
+ * @since 9.5.0
+ */
+ public String getSummary() { return summary; }
+
/**
* Bean property getter: <property>title</property>.
*
@@ -2034,6 +2051,18 @@ public class JsonSchema {
return this;
}
+ /**
+ * Bean property setter: <property>summary</property>.
+ *
+ * @param value The new value for the <property>summary</property>
property on this bean.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public JsonSchema setSummary(String value) {
+ this.summary = value;
+ return this;
+ }
+
/**
* Bean property setter: <property>title</property>.
*
diff --git
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java
index ee81d26120..92efb67998 100644
---
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java
+++
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java
@@ -387,6 +387,12 @@ public class JsonSchemaProperty extends JsonSchema {
return this;
}
+ @Override /* Overridden from JsonSchema */
+ public JsonSchemaProperty setSummary(String value) {
+ super.setSummary(value);
+ return this;
+ }
+
@Override /* Overridden from JsonSchema */
public JsonSchemaProperty setTitle(String value) {
super.setTitle(value);
diff --git
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java
index 1b01676b44..57b4edf50d 100644
---
a/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java
+++
b/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java
@@ -388,6 +388,12 @@ public class JsonSchemaRef extends JsonSchema {
return this;
}
+ @Override /* Overridden from JsonSchema */
+ public JsonSchemaRef setSummary(String value) {
+ super.setSummary(value);
+ return this;
+ }
+
@Override /* Overridden from JsonSchema */
public JsonSchemaRef setTitle(String value) {
super.setTitle(value);
diff --git
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java
index 6125900c19..0390e159da 100644
---
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java
+++
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java
@@ -77,6 +77,16 @@ import java.util.*;
* deprecatedProperty=<jk>true</jk> <jc>// Draft 2020-12
property</jc>
* )
* </p>
+ * <p class='bjava'>
+ * <jc>// AI-friendly short summary paired with a longer description
(since 9.5.0)</jc>
+ * <ja>@Schema</ja>(
+ * summary=<js>"A pet available for adoption"</js>,
+ * description={
+ * <js>"Represents a pet in the store's inventory."</js>,
+ * <js>"Includes details such as name, species, breed,
age, and adoption status."</js>
+ * }
+ * )
+ * </p>
*
* <h5 class='section'>See Also:</h5><ul>
* <li class='link'><a class="doclink"
href="https://juneau.apache.org/docs/topics/JuneauBeanSwagger2";>juneau-bean-swagger-v2</a>
@@ -1499,6 +1509,58 @@ public @interface Schema {
*/
boolean skipIfEmpty() default false;
+ /**
+ * Synonym for {@link #summary()}.
+ *
+ * @return The annotation value.
+ */
+ String su() default "";
+
+ /**
+ * <mk>summary</mk> field of the JSON Schema.
+ *
+ * <p>
+ * A short, concise summary of the schema's purpose.
+ * This is intended to be a brief, single-line description suitable for
AI/LLM consumption,
+ * compact documentation, or any context where brevity is important.
+ *
+ * <p>
+ * Unlike {@link #description()}, which can be multi-line and detailed,
this field should be
+ * kept to a single sentence or phrase that captures the essential
meaning.
+ * The two fields are complementary: {@code summary} is consumed
primarily by AI/LLM tools that
+ * benefit from concise descriptions to minimize token usage and
maximize signal-to-noise ratio,
+ * while {@code description} remains the canonical home for longer
human-readable documentation.
+ *
+ * <p>
+ * This field is a Juneau extension and not part of the standard JSON
Schema or OpenAPI vocabulary
+ * at the Schema Object level. It is modeled after OpenAPI's {@code
summary} keyword on Operation,
+ * Info, and Tag objects.
+ *
+ * <h5 class='section'>Examples:</h5>
+ * <p class='bjava'>
+ * <ja>@Schema</ja>(
+ * summary=<js>"A pet available for adoption"</js>,
+ * description={
+ * <js>"Represents a pet in the store's
inventory."</js>,
+ * <js>"Includes details such as name, species,
breed, age, and adoption status."</js>,
+ * <js>"Pets can be filtered by status using the
/pets endpoint."</js>
+ * }
+ * )
+ * <jk>public class</jk> Pet {...}
+ * </p>
+ *
+ * <h5 class='section'>Notes:</h5><ul>
+ * <li class='note'>
+ * The format is plain text.
+ * <li class='note'>
+ * Supports <a class="doclink"
href="https://juneau.apache.org/docs/topics/RestServerSvlVariables";>SVL
Variables</a> (e.g. <js>"$L{my.localized.variable}"</js>) for the swagger
generator.
+ * </ul>
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* Synonym for {@link #type()}.
*
diff --git
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java
index c05f5ff63a..babff2679e 100644
---
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java
+++
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java
@@ -70,6 +70,19 @@ public @interface BeanProp {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition; this field is the bean-property-level
counterpart.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* Element type for streaming/consuming bean properties.
*
diff --git
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanPropAnnotation.java
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanPropAnnotation.java
index b8ff5cd987..aed93c4c67 100644
---
a/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanPropAnnotation.java
+++
b/juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanPropAnnotation.java
@@ -60,6 +60,7 @@ public class BeanPropAnnotation {
private Class<? extends BeanFactory> factory =
BeanFactory.Void.class;
private String name = "";
private String ro = "";
+ private String summary = "";
private String value = "";
private String wo = "";
@@ -146,6 +147,18 @@ public class BeanPropAnnotation {
return this;
}
+ /**
+ * Sets the {@link BeanProp#summary()} property on this
annotation.
+ *
+ * @param value The new value for this property.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public Builder summary(String value) {
+ summary = value;
+ return this;
+ }
+
/**
* Sets the {@link BeanProp#type()} property on this annotation.
*
@@ -196,6 +209,7 @@ public class BeanPropAnnotation {
private final String name;
private final String value;
private final String ro;
+ private final String summary;
private final String wo;
Object(BeanPropAnnotation.Builder b) {
@@ -206,6 +220,7 @@ public class BeanPropAnnotation {
name = b.name;
params = copyOf(b.params);
ro = b.ro;
+ summary = b.summary;
type = b.type;
value = b.value;
wo = b.wo;
@@ -242,6 +257,11 @@ public class BeanPropAnnotation {
return ro;
}
+ @Override /* Overridden from BeanProp */
+ public String summary() {
+ return summary;
+ }
+
@Override /* Overridden from BeanProp */
public Class<?> type() {
return type;
diff --git
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java
index 80a4b919d1..148d5475fa 100644
---
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java
+++
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java
@@ -75,6 +75,19 @@ public @interface Marshalled {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition; this field is the type-level
counterpart.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* Bean dictionary.
*
diff --git
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/MarshalledAnnotation.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/MarshalledAnnotation.java
index f939b525d8..61bb48b76f 100644
---
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/MarshalledAnnotation.java
+++
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/MarshalledAnnotation.java
@@ -49,6 +49,7 @@ public class MarshalledAnnotation {
private Class<?> implClass = void.class;
private Class<? extends BeanInterceptor<?>> interceptor =
BeanInterceptor.Void.class;
private String example = "";
+ private String summary = "";
private String typeName = "";
private String typePropertyName = "";
@@ -134,6 +135,18 @@ public class MarshalledAnnotation {
return this;
}
+ /**
+ * Sets the {@link Marshalled#summary()} property on this
annotation.
+ *
+ * @param value The new value for this property.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public Builder summary(String value) {
+ summary = value;
+ return this;
+ }
+
/**
* Sets the {@link Marshalled#typeName()} property on this
annotation.
*
@@ -168,6 +181,7 @@ public class MarshalledAnnotation {
private final Class<?> implClass;
private final Class<?>[] dictionary;
private final String example;
+ private final String summary;
private final String typeName;
private final String typePropertyName;
@@ -179,6 +193,7 @@ public class MarshalledAnnotation {
example = b.example;
implClass = b.implClass;
interceptor = b.interceptor;
+ summary = b.summary;
typeName = b.typeName;
typePropertyName = b.typePropertyName;
}
@@ -208,6 +223,11 @@ public class MarshalledAnnotation {
return interceptor;
}
+ @Override /* Overridden from Marshalled */
+ public String summary() {
+ return summary;
+ }
+
@Override /* Overridden from Marshalled */
public String typeName() {
return typeName;
diff --git
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java
index bad1b235c5..dace4f76fd 100644
---
a/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java
+++
b/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java
@@ -74,6 +74,7 @@ public class SchemaAnnotation {
private static final String PROP_readOnly = "readOnly";
private static final String PROP_ref = "$ref";
private static final String PROP_required = "required";
+ private static final String PROP_summary = "summary";
private static final String PROP_then = "then";
private static final String PROP_title = "title";
private static final String PROP_type = "type";
@@ -144,6 +145,8 @@ public class SchemaAnnotation {
private String multipleOf = "";
private String p = "";
private String pattern = "";
+ private String su = "";
+ private String summary = "";
private String t = "";
private String title = "";
private String type = "";
@@ -928,6 +931,30 @@ public class SchemaAnnotation {
return this;
}
+ /**
+ * Sets the {@link Schema#su} property on this annotation.
+ *
+ * @param value The new value for this property.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public Builder su(String value) {
+ su = value;
+ return this;
+ }
+
+ /**
+ * Sets the {@link Schema#summary} property on this annotation.
+ *
+ * @param value The new value for this property.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public Builder summary(String value) {
+ summary = value;
+ return this;
+ }
+
/**
* Sets the {@link Schema#t} property on this annotation.
*
@@ -1066,6 +1093,8 @@ public class SchemaAnnotation {
private final String min;
private final String pattern;
private final String p;
+ private final String su;
+ private final String summary;
private final String type;
private final String t;
private final String collectionFormat;
@@ -1148,6 +1177,8 @@ public class SchemaAnnotation {
ro = b.ro;
sie = b.sie;
skipIfEmpty = b.skipIfEmpty;
+ su = b.su;
+ summary = b.summary;
t = b.t;
title = b.title;
type = b.type;
@@ -1493,6 +1524,16 @@ public class SchemaAnnotation {
return skipIfEmpty;
}
+ @Override /* Overridden from Schema */
+ public String su() {
+ return su;
+ }
+
+ @Override /* Overridden from Schema */
+ public String summary() {
+ return summary;
+ }
+
@Override /* Overridden from Schema */
public String t() {
return t;
@@ -1610,6 +1651,7 @@ public class SchemaAnnotation {
.appendFirst(ne, PROP_pattern, a.pattern(), a.p())
.appendIf(nf, PROP_readOnly, a.readOnly() || a.ro())
.appendIf(nf, PROP_required, a.required() || a.r())
+ .appendFirst(ne, PROP_summary, a.summary(), a.su())
.appendIf(ne, PROP_title, a.title())
.appendFirst(ne, PROP_type, a.type(), a.t())
.appendIf(nf, PROP_uniqueItems, a.uniqueItems() ||
a.ui())
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java
index 5bdf2a783e..d7634a35f6 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java
@@ -127,6 +127,19 @@ public @interface Content {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* <mk>schema</mk> field of the <a class='doclink'
href='https://swagger.io/specification/v2#parameterObject'>Swagger Parameter
Object</a>.
*
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java
index 873b4b0535..f6daf55a86 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java
@@ -134,6 +134,19 @@ public @interface FormData {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* FORM parameter name.
*
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java
index f111526927..84b273ece4 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java
@@ -100,6 +100,19 @@ public @interface Header {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* HTTP header name.
* <p>
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java
index c87c7fea26..d6a21641c0 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java
@@ -98,6 +98,19 @@ public @interface Path {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* URL path variable name.
*
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java
index 958f32de06..71664cea0b 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java
@@ -108,6 +108,19 @@ public @interface Query {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* URL query parameter name.
*
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java
index 1d737fd0aa..1c512461dd 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java
@@ -60,6 +60,19 @@ public @interface Response {
*/
String[] description() default {};
+ /**
+ * Short, concise summary of the exposed API.
+ *
+ * <p>
+ * Intended as a brief, single-line description suitable for AI/LLM
consumption, compact documentation,
+ * or any context where brevity matters. See {@link
org.apache.juneau.commons.annotation.Schema#summary()}
+ * for the canonical definition.
+ *
+ * @return The annotation value.
+ * @since 9.5.0
+ */
+ String summary() default "";
+
/**
* Serialized examples of the body of a response.
*
diff --git
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/ResponseAnnotation.java
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/ResponseAnnotation.java
index a6c3701a14..af72f73987 100644
---
a/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/ResponseAnnotation.java
+++
b/juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/ResponseAnnotation.java
@@ -46,6 +46,7 @@ public class ResponseAnnotation {
private String[] description = {};
private Header[] headers = {};
private Schema schema = SchemaAnnotation.DEFAULT;
+ private String summary = "";
private String[] examples = {};
/**
@@ -108,6 +109,18 @@ public class ResponseAnnotation {
return this;
}
+ /**
+ * Sets the {@link Response#summary()} property on this
annotation.
+ *
+ * @param value The new value for this property.
+ * @return This object.
+ * @since 9.5.0
+ */
+ public Builder summary(String value) {
+ summary = value;
+ return this;
+ }
+
}
@SuppressWarnings({
@@ -120,6 +133,7 @@ public class ResponseAnnotation {
private final String[] description;
private final Header[] headers;
private final Schema schema;
+ private final String summary;
private final String[] examples;
Instance(ResponseAnnotation.Builder b) {
@@ -128,6 +142,7 @@ public class ResponseAnnotation {
examples = copyOf(b.examples);
headers = copyOf(b.headers);
schema = b.schema;
+ summary = b.summary;
}
@Override /* Overridden from Response */
@@ -145,6 +160,11 @@ public class ResponseAnnotation {
return schema;
}
+ @Override /* Overridden from Response */
+ public String summary() {
+ return summary;
+ }
+
@Override /* Overridden from annotation */
public String[] description() {
return description;
diff --git
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java
index 949893b0ed..23b5fac367 100644
---
a/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java
+++
b/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java
@@ -971,6 +971,7 @@ public class BasicSwaggerProviderSession {
.appendFirst(ne, SWAGGER_pattern, a.pattern(),
a.p())
.appendIf(nf, SWAGGER_readOnly, a.readOnly() ||
a.ro())
.appendIf(nf, SWAGGER_required, a.required() ||
a.r())
+ .appendIf(ne, SWAGGER_summary,
resolve(firstNonEmpty(a.summary(), a.su())))
.appendIf(ne, SWAGGER_title, a.title())
.appendFirst(ne, SWAGGER_type, a.type(), a.t())
.appendIf(nf, SWAGGER_uniqueItems,
a.uniqueItems() || a.ui())
diff --git
a/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator_Test.java
b/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator_Test.java
index edcf88238a..9fa49eace0 100644
---
a/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator_Test.java
+++
b/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator_Test.java
@@ -25,6 +25,7 @@ import java.util.*;
import org.apache.juneau.*;
import org.apache.juneau.annotation.*;
import org.apache.juneau.collections.*;
+import org.apache.juneau.commons.annotation.*;
import org.apache.juneau.json.*;
import org.apache.juneau.jsonschema.*;
import org.junit.jupiter.api.*;
@@ -153,6 +154,18 @@ class JsonSchemaBeanGenerator_Test extends TestBase {
assertThrows(RuntimeException.class, () ->
JsonSchemaBeanGenerator.toBean(null));
}
+ @Test void b04_summary_flowsThroughBridge() {
+ var bean =
JsonSchemaBeanGenerator.DEFAULT.generate(SummaryBean.class);
+ assertEquals("A short, AI-friendly description",
bean.getSummary());
+ assertEquals("The user's display name",
bean.getProperty("name").getSummary());
+ }
+
+ @Schema(summary="A short, AI-friendly description")
+ public static class SummaryBean {
+ @Schema(summary="The user's display name")
+ public String name;
+ }
+
public static class SimpleBean {
public String name;
}
diff --git
a/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java
b/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java
index 88d879ec28..03775ead90 100644
---
a/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java
+++
b/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java
@@ -589,4 +589,26 @@ public class JsonSchema_Test extends TestBase {
assertEquals("schema note", x2.getComment());
assertEquals(Boolean.TRUE, x2.getDeprecated());
}
+
+ @Test void b26_summary_roundTrip() throws Exception {
+ var s = Json5Serializer.create().ws().build();
+ var p = Json5Parser.DEFAULT;
+
+ var x = new JsonSchema()
+ .setType(JsonType.STRING)
+ .setSummary("AI-friendly short description");
+
+ var r = s.serialize(x);
+ assertTrue(r.contains("summary: 'AI-friendly short
description'"));
+
+ var x2 = p.parse(r, JsonSchema.class);
+ assertEquals("AI-friendly short description", x2.getSummary());
+ }
+
+ @Test void b27_summary_fluentOverridesOnSubclasses() {
+ var prop = new JsonSchemaProperty("p",
JsonType.STRING).setSummary("prop-summary");
+ var ref = new
JsonSchemaRef("http://x";).setSummary("ref-summary");
+ assertEquals("prop-summary", prop.getSummary());
+ assertEquals("ref-summary", ref.getSummary());
+ }
}
\ No newline at end of file
diff --git
a/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java
b/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java
index 803565c608..56ae6ec6c7 100755
---
a/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java
+++
b/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java
@@ -1521,4 +1521,48 @@ class JsonSchemaGeneratorTest extends TestBase {
public static class MixedStyleExclusiveBean {
public int value;
}
+
+
//====================================================================================================
+ // summary (TODO-6, since 9.5.0)
+
//====================================================================================================
+
+ @Test void summary_typeLevel() throws Exception {
+ var s = JsonSchemaGenerator.DEFAULT.getSession();
+ assertBean(s.getSchema(SummaryBean.class),
"type,summary,description", "object,A pet,Long description");
+ }
+
+ @Test void summary_suAlias() throws Exception {
+ var s = JsonSchemaGenerator.DEFAULT.getSession();
+ assertBean(s.getSchema(SuAliasBean.class), "summary", "alias");
+ }
+
+ @Test void summary_summaryWinsOverSu() throws Exception {
+ var s = JsonSchemaGenerator.DEFAULT.getSession();
+ assertBean(s.getSchema(SummaryWinsBean.class), "summary",
"primary");
+ }
+
+ @Test void summary_propertyLevel() throws Exception {
+ var s = JsonSchemaGenerator.DEFAULT.getSession();
+ assertBean(s.getSchema(SummaryPropertyBean.class),
"properties{name{summary}}", "{{The user's display name}}");
+ }
+
+ @Schema(type="object", summary="A pet", description="Long description")
+ public static class SummaryBean {
+ public String name;
+ }
+
+ @Schema(su="alias")
+ public static class SuAliasBean {
+ public String name;
+ }
+
+ @Schema(summary="primary", su="alias")
+ public static class SummaryWinsBean {
+ public String name;
+ }
+
+ public static class SummaryPropertyBean {
+ @Schema(summary="The user's display name")
+ public String name;
+ }
}
\ No newline at end of file
diff --git
a/juneau-utest/src/test/java/org/apache/juneau/jsonschema/annotation/SchemaAnnotation_Test.java
b/juneau-utest/src/test/java/org/apache/juneau/jsonschema/annotation/SchemaAnnotation_Test.java
index 87ff2b3520..29f145b9b5 100644
---
a/juneau-utest/src/test/java/org/apache/juneau/jsonschema/annotation/SchemaAnnotation_Test.java
+++
b/juneau-utest/src/test/java/org/apache/juneau/jsonschema/annotation/SchemaAnnotation_Test.java
@@ -82,6 +82,8 @@ class SchemaAnnotation_Test extends TestBase {
.readOnly(true)
.required(true)
.ro(true)
+ .su("ee")
+ .summary("dd")
.t("z")
.title("aa")
.type("bb")
@@ -135,6 +137,8 @@ class SchemaAnnotation_Test extends TestBase {
.readOnly(true)
.required(true)
.ro(true)
+ .su("ee")
+ .summary("dd")
.t("z")
.title("aa")
.type("bb")
@@ -145,8 +149,8 @@ class SchemaAnnotation_Test extends TestBase {
@Test void a01_basic() {
assertBean(a1,
-
"$ref,default_,enum_,aev,allOf,allowEmptyValue,cf,collectionFormat,d,description,df,discriminator,e,emax,emin,exclusiveMaximum,exclusiveMinimum,externalDocs{description,url},f,format,ignore,items{$ref,default_,enum_,cf,collectionFormat,description,df,e,emax,emin,exclusiveMaximum,exclusiveMinimum,f,format,items{$ref,default_,enum_,cf,collectionFormat,description,df,e,emax,emin,exclusiveMaximum,exclusiveMinimum,f,format,max,maxItems,maxLength,maxi,maximum,maxl,min,minItems,minLength,min
[...]
-
"c,[a],[b],false,[e],false,f,g,[h],[i],[j],k,[l],true,true,true,true,{[],},m,n,true,{,[],[],,,[],[],[],false,false,false,false,,,{,[],[],,,[],[],[],false,false,false,false,,,,-1,-1,-1,,-1,,-1,-1,-1,,-1,,,,,,,false,false},,-1,-1,-1,,-1,,-1,-1,-1,,-1,,,,,,,false,false},o,2,4,6,1,p,3,5,q,8,10,12,7,r,9,11,s,t,v,w,true,true,true,true,false,false,z,aa,bb,true,true,[cc]");
+
"$ref,default_,enum_,aev,allOf,allowEmptyValue,cf,collectionFormat,d,description,df,discriminator,e,emax,emin,exclusiveMaximum,exclusiveMinimum,externalDocs{description,url},f,format,ignore,items{$ref,default_,enum_,cf,collectionFormat,description,df,e,emax,emin,exclusiveMaximum,exclusiveMinimum,f,format,items{$ref,default_,enum_,cf,collectionFormat,description,df,e,emax,emin,exclusiveMaximum,exclusiveMinimum,f,format,max,maxItems,maxLength,maxi,maximum,maxl,min,minItems,minLength,min
[...]
+
"c,[a],[b],false,[e],false,f,g,[h],[i],[j],k,[l],true,true,true,true,{[],},m,n,true,{,[],[],,,[],[],[],false,false,false,false,,,{,[],[],,,[],[],[],false,false,false,false,,,,-1,-1,-1,,-1,,-1,-1,-1,,-1,,,,,,,false,false},,-1,-1,-1,,-1,,-1,-1,-1,,-1,,,,,,,false,false},o,2,4,6,1,p,3,5,q,8,10,12,7,r,9,11,s,t,v,w,true,true,true,true,false,false,ee,dd,z,aa,bb,true,true,[cc]");
}
@Test void a02_testEquivalency() {
@@ -218,6 +222,8 @@ class SchemaAnnotation_Test extends TestBase {
readOnly=true,
required=true,
ro=true,
+ su="ee",
+ summary="dd",
t="z",
title="aa",
type="bb",
@@ -273,6 +279,8 @@ class SchemaAnnotation_Test extends TestBase {
readOnly=true,
required=true,
ro=true,
+ su="ee",
+ summary="dd",
t="z",
title="aa",
type="bb",
@@ -438,4 +446,32 @@ class SchemaAnnotation_Test extends TestBase {
assertBean(mixed,
"exclusiveMaximum,exclusiveMinimum,exclusiveMaximumValue,exclusiveMinimumValue",
"false,false,100,0");
}
+
+
//------------------------------------------------------------------------------------------------------------------
+ // summary / su (TODO-6, since 9.5.0)
+
//------------------------------------------------------------------------------------------------------------------
+
+ @Test void g01_summary_asMap_emptyAnnotationOmitsKey() throws Exception
{
+
assertFalse(SchemaAnnotation.asMap(SchemaAnnotation.DEFAULT).containsKey("summary"));
+ }
+
+ @Test void g02_summary_asMap_summaryWins() throws Exception {
+ var a =
SchemaAnnotation.create().summary("the-real-summary").build();
+ assertEquals("the-real-summary",
SchemaAnnotation.asMap(a).get("summary"));
+ }
+
+ @Test void g03_summary_asMap_suAliasUsedWhenSummaryEmpty() throws
Exception {
+ var a = SchemaAnnotation.create().su("from-alias").build();
+ assertEquals("from-alias",
SchemaAnnotation.asMap(a).get("summary"));
+ }
+
+ @Test void g04_summary_asMap_summaryTakesPrecedenceOverSu() throws
Exception {
+ var a =
SchemaAnnotation.create().summary("primary").su("alias").build();
+ assertEquals("primary",
SchemaAnnotation.asMap(a).get("summary"));
+ }
+
+ @Test void g05_summary_emptyValueOmitsKey() throws Exception {
+ var a = SchemaAnnotation.create().summary("").su("").build();
+ assertFalse(SchemaAnnotation.asMap(a).containsKey("summary"));
+ }
}
\ No newline at end of file
diff --git a/todo/FINISHED-6-ai-short-description.md
b/todo/FINISHED-6-ai-short-description.md
new file mode 100644
index 0000000000..28bbcf0afd
--- /dev/null
+++ b/todo/FINISHED-6-ai-short-description.md
@@ -0,0 +1,278 @@
+# AI Short Description Field for Schema Annotations
+
+## Overview
+
+Add a short-form description field to `@Schema` (and a small set of related
annotations) designed primarily for AI / LLM consumption. When AI systems
consume JSON Schemas generated by Juneau (e.g. for tool calling, function
definitions, or structured output), concise descriptions are critical for
accurate interpretation while minimizing token usage. The existing
`description` field supports multi-line, human-readable documentation which is
often too verbose for AI contexts.
+
+## Problem
+
+The current `description` / `d` field on `@Schema` is a `String[]` that
concatenates multiple lines with newlines. Descriptions written for Swagger /
OpenAPI documentation tend to be detailed and human-oriented. When these
schemas are consumed by LLMs (e.g. as tool definitions for function calling, or
as structured output schemas), verbose descriptions waste tokens and can dilute
the signal that guides model behaviour.
+
+There is currently no standard mechanism in Juneau to provide a separate,
concise description optimized for AI consumption.
+
+## Industry precedent
+
+### JSON Schema standard
+
+JSON Schema (Draft 2020-12) defines two annotation keywords relevant to short
descriptions:
+
+- **`title`** — short label / name for the schema (already supported in
`@Schema`).
+- **`description`** — longer explanation of the schema's purpose.
+
+There is no standard "short description" or "summary" keyword in JSON Schema
itself.
+
+### OpenAPI
+
+OpenAPI defines a `summary` field on `Operation`, `Info`, and `Tag` objects,
but **not** on `Schema` objects. `summary` is "a short summary of what the
operation does" and is distinct from the longer `description`.
+
+### Microsoft `x-ai-*` extension
+
+Microsoft introduced `x-ai-description` as a custom OpenAPI extension
(`x-ai-*` family) specifically for AI plugin integrations (Microsoft 365
Copilot). This provides AI-optimized descriptions that complement standard
documentation fields.
+
+### LLM tool calling
+
+Production experience (2025-2026) shows that JSON Schema `description` fields
are the primary mechanism LLMs use to understand field semantics during tool
calling. Short, precise descriptions produce more reliable results than verbose
documentation.
+
+## Naming analysis
+
+### Option A: `summary` (alias `su`)
+
+| Aspect | Assessment |
+|--------|------------|
+| Familiarity | Well-known from OpenAPI `Operation` objects. |
+| JSON Schema alignment | Not a standard JSON Schema keyword, but widely
understood. |
+| Semantics | "A short summary" — generic, not AI-specific. |
+| Output key | `summary` (no `x-` prefix needed). |
+| Precedent | OpenAPI uses `summary` + `description` as a pair on Operations. |
+
+**Pro:** Natural pair with `description`. Developers immediately understand
the intent.<br/>
+**Con:** Not a standard Schema Object property in OpenAPI or JSON Schema, so
it is a custom extension. Not explicitly tied to AI purpose.
+
+### Option B: `aiDescription` (alias `aid`)
+
+| Aspect | Assessment |
+|--------|------------|
+| Familiarity | Novel, but self-documenting. |
+| JSON Schema alignment | Custom extension; serializes as `x-ai-description`. |
+| Semantics | Explicitly AI-focused. |
+| Output key | `x-ai-description`. |
+| Precedent | Microsoft's `x-ai-description` extension. |
+
+**Pro:** Clear intent. Follows Microsoft's `x-ai-*` convention. Separates AI
concerns from documentation concerns.<br/>
+**Con:** More opinionated. Ties the feature to AI specifically even though
short descriptions have broader utility.
+
+### Option C: `shortDescription` (alias `sd`)
+
+| Aspect | Assessment |
+|--------|------------|
+| Familiarity | Self-explanatory. |
+| JSON Schema alignment | Custom extension. |
+| Semantics | Describes the format (short) rather than the consumer (AI). |
+| Output key | `x-short-description` or `shortDescription`. |
+| Precedent | None direct. |
+
+**Pro:** Very descriptive of what it is.<br/>
+**Con:** Verbose annotation name. No industry precedent. Doesn't communicate
the AI-oriented purpose.
+
+### Recommendation
+
+**Use `summary` / `su`.** Rationale:
+
+1. **Familiar pairing** — OpenAPI established `summary` + `description` as a
short / long pair. Developers already understand this convention.
+2. **Not AI-exclusive** — While the primary motivation is AI consumption,
short descriptions are useful in other contexts (compact docs, tooltips, list
views). A generic name avoids artificially limiting the feature.
+3. **Clean output** — Serializes as `"summary"` in the JSON Schema output
without requiring the `x-` extension prefix, keeping schemas clean.
+4. **Consistent with Juneau style** — Single-word field names with short
aliases (`d` for `description`, `t` for `type`, etc.) are the established
pattern. `summary` / `su` fits naturally.
+5. **Future-proof** — If JSON Schema or OpenAPI ever add a `summary` keyword
to Schema objects, Juneau is already aligned.
+
+The AI-oriented purpose should be documented in the Javadoc, making it clear
that the field is designed for concise descriptions suitable for AI / LLM
consumption while remaining useful for any context requiring brevity.
+
+---
+
+## Current state of the relevant files (audit)
+
+These paths were verified against the repo on the latest commit and supersede
the older draft of this plan:
+
+| Purpose | Current path |
+|---------|--------------|
+| `@Schema` annotation |
`juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java`
|
+| `@Schema` processor |
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java`
|
+| Marshall type annotation (was `@Bean`) |
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java`
|
+| Bean-property annotation (was `@Beanp`) |
`juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java`
|
+| HTTP `@Response` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java`
|
+| HTTP `@Header` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java`
|
+| HTTP `@Query` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java`
|
+| HTTP `@Path` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java`
|
+| HTTP `@FormData` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java`
|
+| HTTP `@Content` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java`
|
+| HTTP annotation processors that already exist |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/{ContactAnnotation,LicenseAnnotation,ResponseAnnotation,TagAnnotation}.java`
|
+| JSON Schema generator |
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGenerator.java`
|
+| JSON Schema generator session |
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorSession.java`
|
+| `JsonSchema` bean |
`juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java`
|
+| `JsonSchemaProperty` bean |
`juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java`
|
+| `JsonSchemaRef` bean |
`juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java`
|
+| `JsonSchemaBeanGenerator` (TODO-8 bridge) |
`juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator.java`
|
+| Swagger provider session |
`juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java`
|
+
+### Patterns to mirror
+
+- **Java field naming** — `@Schema.description()` returns `String[]`;
`@Schema.title()` returns `String`. **`summary` should be `String`** (single
line by design), aliased as `su()` (matches `t` / `f` / `p`).
+- **`SchemaAnnotation.asMap()`** — multi-value descriptions use `appendIf(ne,
PROP_description, joinnl(a.description(), a.d()))`. Single-value strings such
as `title` / `format` use `appendIf(ne, PROP_title, a.title())` or
`appendFirst(ne, PROP_format, a.format(), a.f())`. **`summary` uses the
`appendFirst` pattern** because there is a synonym alias.
+- **`SchemaAnnotation.Builder`** — single-string fields like `title` declare
`private String title = "";` plus a fluent setter. `summary` follows the same
shape.
+- **JSON Schema bean field additions** — TODO-8 just added `format`,
`$comment`, and `deprecated` to `JsonSchema` with paired fluent setters on
`JsonSchemaProperty` / `JsonSchemaRef`. `summary` follows the exact same
pattern; see the `getFormat()` / `setFormat()` /
`JsonSchemaProperty.setFormat()` triple as the template.
+
+---
+
+## Plan
+
+### Phase 1 — Add `summary` / `su` to `@Schema`
+
+**File:**
`juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/annotation/Schema.java`
+
+Insert two new annotation methods between `subItems` and `t()` (alphabetic /
synonym order matches the surrounding declarations):
+
+```java
+String summary() default "";
+String su() default "";
+```
+
+Javadoc for `summary()` should:
+
+- Describe the purpose as "short, concise summary" suitable for AI / LLM
consumption, compact docs, tooltips, etc.
+- Cross-reference `description()` and explain the brevity intent.
+- Note that the value is plain text and supports SVL variables for the Swagger
generator (same as `description`).
+- Include a concrete example using `summary=...` alongside multi-line
`description={...}`.
+
+Javadoc for `su()` is the synonym-of-`summary()` stub, matching `t()` / `f()`
/ etc.
+
+### Phase 2 — Wire `summary` through `SchemaAnnotation`
+
+**File:**
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java`
+
+1. **Add property constant** alongside the existing `PROP_*` block:
+
+ ```java
+ private static final String PROP_summary = "summary";
+ ```
+
+2. **Builder field + fluent setter (+ alias setter)** in the `Builder` inner
class, alphabetic order:
+
+ ```java
+ private String summary = "";
+ public Builder summary(String value) { this.summary = value; return this; }
+ public Builder su(String value) { this.summary = value; return this; }
+ ```
+
+3. **`asMap(Schema a)`** — add an `appendFirst` entry near the existing
`PROP_title` row:
+
+ ```java
+ .appendFirst(ne, PROP_summary, a.summary(), a.su())
+ ```
+
+ (Use `appendFirst` because `summary` is a single string with an alias,
mirroring `format` / `type`.)
+
+4. **`empty(Schema a)`** and the `DEFAULT` annotation proxy must include
`summary` (default `""`) so the `empty` predicate stays correct.
+
+### Phase 3 — Add `summary` to companion annotations
+
+These annotations all already expose `description`; adding `summary` keeps the
pair complete.
+
+| Annotation | File | Notes |
+|------------|------|-------|
+| `@Marshalled` |
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Marshalled.java`
| Was `@Bean.description` in older releases. |
+| `@BeanProp` |
`juneau-core/juneau-commons/src/main/java/org/apache/juneau/commons/bean/BeanProp.java`
| Was `@Beanp.description` in older releases. |
+| `@Response` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Response.java`
| Has matching `ResponseAnnotation` processor. |
+| `@Header` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Header.java`
| No dedicated `*Annotation` processor — verify wiring path during impl. |
+| `@Query` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Query.java`
| Same caveat. |
+| `@Path` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Path.java`
| Same caveat. |
+| `@FormData` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/FormData.java`
| Same caveat. |
+| `@Content` |
`juneau-rest/juneau-rest-common/src/main/java/org/apache/juneau/http/annotation/Content.java`
| Same caveat. |
+
+For each annotation:
+
+- Add `String summary() default "";`.
+- If a sibling `*Annotation.java` processor exists (`ResponseAnnotation`
does), add `PROP_summary` constant + `Builder` field/setter + a row in
`asMap()`.
+- If no sibling processor exists, the per-annotation map is built via generic
annotation processing; trace `description` consumption to find where `summary`
should be picked up and add it alongside.
+
+### Phase 4 — Propagate `summary` through the JSON Schema generator
+
+**File:**
`juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorSession.java`
+
+`getSchema(...)` already merges the full `SchemaAnnotation.asMap()` output
into its `JsonMap` result, so once Phase 2 lands `summary` flows through
automatically.
+
+However the session also has explicit handling for a handful of well-known
keys (`description`, `title`, etc.). Add the equivalent line:
+
+```java
+out.appendIfAbsentIf(neo, "summary", summary);
+```
+
+so that values inferred from class-level `@Schema` are honoured even when no
JSON map merge happens for that property.
+
+No changes are required in `JsonSchemaClassMeta` or
`JsonSchemaBeanPropertyMeta` — both collect the entire `@Schema` annotation map.
+
+### Phase 5 — Add `summary` to the `JsonSchema` bean
+
+Mirror the pattern that TODO-8 just established for `format` / `$comment` /
`deprecated`.
+
+**`JsonSchema.java`:**
+
+```java
+private String summary;
+
+public String getSummary() { return summary; }
+
+public JsonSchema setSummary(String value) {
+ this.summary = value;
+ return this;
+}
+```
+
+**`JsonSchemaProperty.java` + `JsonSchemaRef.java`** — fluent overrides:
+
+```java
+@Override
+public JsonSchemaProperty setSummary(String value) {
+ super.setSummary(value);
+ return this;
+}
+```
+
+`JsonSchemaBeanGenerator` (TODO-8 bridge) needs **no changes** — it goes
through a JSON round-trip and will pick up `"summary"` automatically as soon as
`JsonSchema` has the property.
+
+### Phase 6 — Swagger / OpenAPI generation
+
+**File:**
`juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java`
+
+Find every spot that copies `description` from a schema annotation into the
generated Swagger / OpenAPI structures and add a sibling line for `summary`.
Most sites should be a 1-line change because the session leans on
`SchemaAnnotation.asMap()` output already.
+
+### Phase 7 — Tests
+
+| Suite | File | Cases |
+|-------|------|-------|
+| Schema annotation |
`juneau-utest/src/test/java/org/apache/juneau/annotation/` (add
`SchemaAnnotation_Test` if absent, otherwise extend) | `asMap` includes
`summary`; `appendFirst` precedence (`summary` over `su`); empty defaults are
omitted. |
+| Schema generator |
`juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java`
| `@Schema(summary="...")` on type and property produce `"summary"` in JSON
Schema; `su` alias parity; `summary` + `description` coexist. |
+| JSON Schema bean |
`juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java`
| `getSummary()` / `setSummary()` round-trip; serialize includes `"summary"`;
`JsonSchemaProperty.setSummary(...)` returns the subtype. |
+| Bean generator bridge |
`juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchemaBeanGenerator_Test.java`
| Add one test that puts `@Schema(summary=...)` on a property and verifies the
resulting `JsonSchema.getProperty(...).getSummary()` returns the value,
asserting the bridge picks up `summary` for free. |
+| Swagger | `juneau-utest/src/test/java/org/apache/juneau/rest/swagger/` |
Verify generated Swagger objects expose `summary` from `@Schema` annotations. |
+
+### Phase 8 — Documentation
+
+- Class-level Javadoc on `Schema.java` — add a one-liner mentioning `summary`
and its purpose under the existing `Examples:` section.
+- `juneau-docs/pages/release-notes/9.5.0.md` — add a bullet under
`juneau-marshall` describing the new field, with a short example.
+- `juneau-docs/pages/topics/02.25.JsonSchemaDetails.md` — extend the
schema-annotation section to call out the `summary` field, including the
AI-consumption motivation.
+- `@since 9.5.0` tags on every new public symbol.
+
+### Phase 9 — Verify & archive
+
+1. `./scripts/test.py --full` — full reactor build + tests.
+2. `./scripts/coverage.py
juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java
--branches` — confirm new branches covered.
+3. `./scripts/coverage.py
juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java
--branches` — confirm the new accessor is covered.
+4. `/todo cleanup 6` — once everything lands, archive the plan as
`FINISHED-6-ai-short-description.md` and remove the `[TODO-6]` line from
`todo/TODO.md`.
+
+---
+
+## Risks / notes
+
+- **Schema-validation impact** — `summary` is a documentation-only field; it
must not feed into `SchemaValidationException` / validation paths. Confirm the
validators (`HttpPartSchema.Builder.apply(...)` etc.) ignore it.
+- **OpenAPI bean alignment (`juneau-bean-swagger-v2`,
`juneau-bean-openapi-v3`)** — those beans already have `summary` on `Operation`
/ `Info` / `Tag`. Avoid accidentally adding it to a `Schema` bean in those
packages unless OpenAPI itself starts allowing it — keep it Juneau-side only.
+- **Annotation surface creep** — only add `summary` to the same set of
annotations that already carry `description`. Resist adding it to single-use
marker annotations.
+- **Naming lock-in** — once `summary` lands on `@Schema`, removing or renaming
it would be a breaking change. The single-string shape (no `String[]`) is the
easiest contract to commit to.
diff --git a/todo/TODO-6-ai-short-description.md
b/todo/TODO-6-ai-short-description.md
deleted file mode 100644
index a90f638813..0000000000
--- a/todo/TODO-6-ai-short-description.md
+++ /dev/null
@@ -1,320 +0,0 @@
-# AI Short Description Field for Schema Annotations
-
-## Overview
-
-Add a short-form description field to `@Schema` (and related annotations)
designed primarily for AI/LLM consumption. When AI systems consume JSON Schemas
generated by Juneau (e.g., for tool calling, function definitions, or
structured output), concise descriptions are critical for accurate
interpretation while minimizing token usage. The existing `description` field
supports multi-line, human-readable documentation which is often too verbose
for AI contexts.
-
-## Problem
-
-The current `description` / `d` field on `@Schema` is a `String[]` that
concatenates multiple lines with newlines. Descriptions written for
Swagger/OpenAPI documentation tend to be detailed and human-oriented. When
these schemas are consumed by LLMs (e.g., as tool definitions for function
calling, or as structured output schemas), verbose descriptions waste tokens
and can dilute the signal that guides model behavior.
-
-There is currently no standard mechanism in Juneau to provide a separate,
concise description optimized for AI consumption.
-
-## Industry Precedent
-
-### JSON Schema Standard
-JSON Schema (Draft 2020-12) defines two annotation keywords relevant to short
descriptions:
-- **`title`** -- A short label/name for the schema (already supported in
`@Schema`)
-- **`description`** -- A longer explanation of the schema's purpose
-
-There is no standard "short description" or "summary" keyword in JSON Schema
itself.
-
-### OpenAPI
-OpenAPI defines a `summary` field on Operation, Info, and Tag objects, but
**not** on Schema objects. The `summary` field is described as "a short summary
of what the operation does" and is distinct from the longer `description`.
-
-### Microsoft OpenAPI Extensions
-Microsoft introduced `x-ai-description` as a custom OpenAPI extension
(`x-ai-*` family) specifically for AI plugin integrations (Microsoft 365
Copilot). This provides AI-optimized descriptions that complement standard
documentation fields.
-
-### LLM Tool Calling
-Research and production experience (2025-2026) shows that JSON Schema
`description` fields are the primary mechanism LLMs use to understand field
semantics during tool calling. Short, precise descriptions produce more
reliable results than verbose documentation.
-
-## Naming Analysis
-
-### Option A: `summary` (alias `su`)
-
-| Aspect | Assessment |
-|--------|------------|
-| Familiarity | Well-known from OpenAPI Operation objects |
-| JSON Schema alignment | Not a standard JSON Schema keyword, but widely
understood |
-| Semantics | "A short summary" -- generic, not AI-specific |
-| Output key | `summary` or `x-summary` |
-| Precedent | OpenAPI uses `summary` + `description` as a pair on Operations |
-
-**Pro:** Natural pair with `description`. Developers immediately understand
the intent.
-**Con:** Not a standard Schema Object property in OpenAPI or JSON Schema, so
it would be a custom extension. Not explicitly tied to AI purpose.
-
-### Option B: `aiDescription` (alias `aid`)
-
-| Aspect | Assessment |
-|--------|------------|
-| Familiarity | Novel, but self-documenting |
-| JSON Schema alignment | Custom extension; would serialize as
`x-ai-description` |
-| Semantics | Explicitly AI-focused |
-| Output key | `x-ai-description` |
-| Precedent | Microsoft's `x-ai-description` extension |
-
-**Pro:** Clear intent. Follows Microsoft's `x-ai-*` convention. Separates AI
concerns from documentation concerns.
-**Con:** More opinionated. Ties the feature to AI specifically even though
short descriptions have broader utility.
-
-### Option C: `shortDescription` (alias `sd`)
-
-| Aspect | Assessment |
-|--------|------------|
-| Familiarity | Self-explanatory |
-| JSON Schema alignment | Custom extension |
-| Semantics | Describes the format (short) rather than the consumer (AI) |
-| Output key | `x-short-description` or `shortDescription` |
-| Precedent | No direct precedent |
-
-**Pro:** Very descriptive of what it is.
-**Con:** Verbose annotation name. No industry precedent. Doesn't communicate
the AI-oriented purpose.
-
-## Recommendation
-
-**Use `summary` / `su`** as the field name.
-
-Rationale:
-1. **Familiar pairing** -- OpenAPI established the `summary` + `description`
pattern as a short/long pair. Developers already understand this convention.
-2. **Not AI-exclusive** -- While the primary motivation is AI consumption,
short descriptions are useful in other contexts (compact documentation,
tooltips, list views). A generic name avoids artificially limiting the feature.
-3. **Clean output** -- Can serialize as `"summary"` in the JSON Schema output
without requiring the `x-` extension prefix, keeping schemas clean.
-4. **Consistent with Juneau style** -- Single-word field names with short
aliases (`d` for `description`, `t` for `type`, etc.) are the established
pattern. `summary` / `su` fits naturally.
-5. **Future-proof** -- If JSON Schema or OpenAPI ever adds a `summary` keyword
to Schema objects, Juneau would already be aligned.
-
-The AI-oriented purpose should be documented in the Javadoc, making it clear
that the field is designed for concise descriptions suitable for AI/LLM
consumption while remaining useful for any context requiring brevity.
-
----
-
-## Phase 1: Add `summary` / `su` to `@Schema` Annotation
-
-**File:**
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Schema.java`
-
-Add two new annotation methods following the existing `description` / `d`
pattern:
-
-```java
-/**
- * <mk>summary</mk> field of the JSON Schema.
- *
- * <p>
- * A short, concise summary of the schema's purpose.
- * This is intended to be a brief, single-line description suitable for AI/LLM
consumption,
- * compact documentation, or any context where brevity is important.
- *
- * <p>
- * Unlike {@link #description()}, which can be multi-line and detailed, this
field should be
- * kept to a single sentence or phrase that captures the essential meaning.
- *
- * <h5 class='section'>Example:</h5>
- * <p class='bjava'>
- * <ja>@Schema</ja>(
- * summary=<js>"A pet available for adoption"</js>,
- * description={
- * <js>"Represents a pet in the store's inventory."</js>,
- * <js>"Includes details such as name, species, breed,
age, and adoption status."</js>,
- * <js>"Pets can be filtered by status using the /pets
endpoint."</js>
- * }
- * )
- * <jk>public class</jk> Pet {...}
- * </p>
- *
- * <h5 class='section'>Notes:</h5><ul>
- * <li class='note'>
- * The format is plain text.
- * <li class='note'>
- * Supports <a class="doclink" href="...">SVL Variables</a> for
the swagger generator.
- * </ul>
- *
- * @return The annotation value.
- */
-String summary() default "";
-
-/**
- * Synonym for {@link #summary()}.
- *
- * @return The annotation value.
- */
-String su() default "";
-```
-
-Note: `summary` is a `String` (not `String[]`) since by design it should be a
single concise value, reinforcing the intent of brevity. This also
distinguishes it from `description` / `d` which are `String[]`.
-
----
-
-## Phase 2: Update `SchemaAnnotation` Processor
-
-**File:**
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java`
-
-### 2a. Add property constant
-
-```java
-private static final String PROP_summary = "summary";
-```
-
-### 2b. Update `asMap()` method
-
-Add to the `asMap()` chain (near the existing `PROP_description` line):
-
-```java
-.appendFirst(ne, PROP_summary, a.summary(), a.su())
-```
-
-This uses `appendFirst` (first non-empty wins) since `summary` is a
single-value `String`, matching the pattern used by `format`, `type`, etc.
-
-### 2c. Update `Builder` class
-
-Add `summary` field, getter, setter, and alias setter to the `Builder` inner
class, following the existing pattern for single-value string fields like
`format`:
-
-```java
-private String summary = "";
-
-public Builder summary(String value) { this.summary = value; return this; }
-public Builder su(String value) { this.summary = value; return this; }
-```
-
-### 2d. Update `empty()` check and `DEFAULT`
-
-Ensure the default annotation proxy includes `summary` and `su` with
empty-string defaults.
-
----
-
-## Phase 3: Add `summary` to Related Annotations
-
-The `description` field was added to several annotations in v9.2.0. The
`summary` field should be added to the same set for consistency.
-
-### Annotations to update:
-
-| Annotation | File |
-|-----------|------|
-| `@Bean` | `juneau-core/juneau-marshall/.../annotation/Bean.java` |
-| `@Beanp` | `juneau-core/juneau-marshall/.../annotation/Beanp.java` |
-| `@Response` |
`juneau-core/juneau-marshall/.../http/annotation/Response.java` |
-| `@Header` | `juneau-core/juneau-marshall/.../http/annotation/Header.java` |
-| `@Query` | `juneau-core/juneau-marshall/.../http/annotation/Query.java` |
-| `@Path` | `juneau-core/juneau-marshall/.../http/annotation/Path.java` |
-| `@FormData` |
`juneau-core/juneau-marshall/.../http/annotation/FormData.java` |
-| `@Content` | `juneau-core/juneau-marshall/.../http/annotation/Content.java` |
-
-For each annotation:
-- Add `String summary() default "";`
-- Update the corresponding `*Annotation.java` processor class to include
`summary` in its map conversion
-
----
-
-## Phase 4: Update JSON Schema Generator
-
-**File:**
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorSession.java`
-
-Update `getSchema()` to propagate `summary` from the schema annotation into
the output `JsonMap`, similar to how `description` is handled:
-
-```java
-out.appendIfAbsentIf(neo, "summary", summary);
-```
-
-The `summary` value flows from `@Schema` annotation ->
`SchemaAnnotation.asMap()` -> `JsonSchemaClassMeta.getSchema()` /
`JsonSchemaBeanPropertyMeta.getSchema()` ->
`JsonSchemaGeneratorSession.getSchema()` output. No changes needed in
`JsonSchemaClassMeta` or `JsonSchemaBeanPropertyMeta` since they already
collect and merge the full `@Schema` map.
-
----
-
-## Phase 5: Update `JsonSchema` Bean
-
-**File:**
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java`
-
-Add a `summary` property to the `JsonSchema` bean class:
-
-```java
-private String summary;
-
-public String getSummary() { return summary; }
-
-public JsonSchema setSummary(String value) {
- this.summary = value;
- return this;
-}
-```
-
-**File:**
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java`
-
-Add fluent override:
-
-```java
-@Override
-public JsonSchemaProperty setSummary(String value) {
- super.setSummary(value);
- return this;
-}
-```
-
-**File:**
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java`
-
-Add fluent override (same pattern).
-
----
-
-## Phase 6: Update Swagger/OpenAPI Generation
-
-**File:**
`master/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java`
-
-Ensure `summary` values from `@Schema` annotations are propagated into the
generated Swagger/OpenAPI documentation. This file already processes
`description` from schema annotations; `summary` should be handled in the same
locations.
-
----
-
-## Phase 7: Testing
-
-**File:**
`master/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java`
-
-Add test cases:
-- `@Schema(summary="...")` on a class produces `"summary": "..."` in JSON
Schema output
-- `@Schema(su="...")` alias works identically
-- `summary` and `description` coexist independently in output
-- `summary` on bean properties appears in the `properties` map of the schema
-
-**File:**
`master/juneau-utest/src/test/java/org/apache/juneau/annotation/SchemaAnnotation_Test.java`
(or equivalent)
-
-- Test `asMap()` includes `summary` when set
-- Test `appendFirst` precedence: `summary` takes priority over `su` when both
set
-- Test default (empty) is omitted from map
-
-**File:**
`master/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java`
-
-- Test `setSummary()` / `getSummary()` round-trip
-- Test serialization includes `"summary"` in JSON output
-
----
-
-## Phase 8: Documentation
-
-- Update `Schema.java` class-level Javadoc to mention `summary` in the overview
-- Update any developer guide pages that discuss schema annotations
-- Add `@since` tags with the appropriate version number
-
----
-
-## Key Files Reference
-
-**Annotation definitions:**
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Schema.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Bean.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/Beanp.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Response.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Header.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Query.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Path.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/FormData.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/http/annotation/Content.java`
-
-**Annotation processors:**
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/annotation/SchemaAnnotation.java`
-
-**JSON Schema generation:**
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorSession.java`
--
`master/juneau-core/juneau-marshall/src/main/java/org/apache/juneau/jsonschema/JsonSchemaGenerator.java`
-
-**JSON Schema beans:**
--
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchema.java`
--
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaProperty.java`
--
`master/juneau-bean/juneau-bean-jsonschema/src/main/java/org/apache/juneau/bean/jsonschema/JsonSchemaRef.java`
-
-**Swagger generation:**
--
`master/juneau-rest/juneau-rest-server/src/main/java/org/apache/juneau/rest/swagger/BasicSwaggerProviderSession.java`
-
-**Tests:**
--
`master/juneau-utest/src/test/java/org/apache/juneau/jsonschema/JsonSchemaGeneratorTest.java`
--
`master/juneau-utest/src/test/java/org/apache/juneau/bean/jsonschema/JsonSchema_Test.java`
diff --git a/todo/TODO-7-decouple-rest-common-from-marshall.md
b/todo/TODO-7-decouple-rest-common-from-marshall.md
index 37e42efe8b..6d939b59d7 100644
--- a/todo/TODO-7-decouple-rest-common-from-marshall.md
+++ b/todo/TODO-7-decouple-rest-common-from-marshall.md
@@ -7,66 +7,174 @@ juneau-commons -> juneau-rest-common -> juneau-marshall ->
juneau-rest-client
-> juneau-rest-server
```
-Phases **1a** (HTTP types in commons), **1b** (annotation types in commons),
and **2** (enums/exceptions/`HttpPartSchema` refactor, annotation cleanup) are
**done** — details removed from this plan to avoid noise.
+`juneau-rest-common/pom.xml` still declares a compile dep on
`juneau-marshall`. The remaining gap below is the work needed to drop it.
-**Current gap:** `juneau-rest-common` **still** compile-depends on
`juneau-marshall` (`SchemaAnnotation`, `InvalidAnnotationException`,
serializers, refactored-but-not-moved `HttpPartSchema`, bean/httppart meta,
etc.).
+---
+
+## Already landed (no further action)
+
+- **Phase 1a — commons HTTP types** — `MediaRange` / `MediaRanges` /
`MediaType` / `StringRange` / `StringRanges` live in
`org.apache.juneau.commons.http`.
+- **Phase 1b — commons annotations** — `@Schema` family lives in
`org.apache.juneau.commons.annotation`.
+- **Phase 2 (initial) — httppart enums + exception in commons** —
`HttpPartType`, `HttpPartFormat`, `HttpPartDataType`,
`HttpPartCollectionFormat`, `SchemaValidationException` live in
`org.apache.juneau.commons.httppart`.
+- **SVL in commons (TODO-14)** — `VarResolverSession` and friends in
`org.apache.juneau.commons.svl`; `HeaderList` / `PartList` no longer pull
marshall for variable resolution.
+- **BeanCreator → BeanInstantiator (TODO-15)** — rest-common's
`RequestBeanMeta` / `RequestBeanPropertyMeta` / `ResponseBeanPropertyMeta` now
use `org.apache.juneau.commons.inject.BeanInstantiator` (commons). The "move
`BeanCreator` or use `ClassInfo.newInstance()`" Phase 4 row is done.
+- **`juneau-assertions` direct dep** — `juneau-rest-common/pom.xml` already
declares `juneau-assertions` directly (no longer transitive only through
marshall).
+
+> The plan from here lists **only** what is still required to drop the
`juneau-marshall` dep from rest-common.
---
-## Phase 2 follow-through — move `HttpPartSchema` to commons (deferred)
+## Current marshall surface still imported by rest-common
-`HttpPartSchema` remains in marshall until these are addressed:
+Verified by `rg ^import
org\.apache\.juneau\.(serializer|parser|oapi|urlencoding|json|jsonschema|annotation\.[A-Z]|httppart\.[A-Z])`
under `juneau-rest-common/src/main/java`.
-- `apply(HttpPartMarshalling)` on the builder ties to marshall’s
`HttpPartMarshalling`
-- References to `*Annotation.empty()` (e.g. `ItemsAnnotation.DEFAULT`,
`SubItemsAnnotation.DEFAULT`)
-- `ParseException` import from marshall
+### A. Httppart marshalling surface (the big one)
-**Lower priority:** strip Creator inner classes from `HttpPartSerializer` /
`HttpPartParser` (can stay in marshall regardless).
+Symbols still in `org.apache.juneau.httppart` (marshall):
-**Keep in marshall by design:** `HttpPartSerializer`, `HttpPartParser`,
`HttpPartMarshalling` (serializer/parser surface).
+- `HttpPartSchema` (+ `Builder`, `DEFAULT`)
+- `HttpPartSerializer` / `HttpPartSerializerSession`
+- `HttpPartParser` / `HttpPartParserSession`
+- `HttpPart` interface
+- `HttpPartMarshalling`
----
+Rest-common consumers:
+
+- `httppart/bean/RequestBeanMeta`, `ResponseBeanMeta`,
`RequestBeanPropertyMeta`, `ResponseBeanPropertyMeta`
+- `http/header/HeaderBeanMeta`, `http/header/SerializedHeader`
+- `http/part/PartBeanMeta`, `http/part/SerializedPart`
+- `http/entity/SerializedEntity`
+- `http/HttpHeaders` (`serializedHeader(...)` factories)
+- `http/HttpEntities` (`serializedEntity(...)` factory)
+- `http/HttpParts` (uses `HttpPartType` + `ClassMeta<?>`)
+
+### B. Serializer surface (Phase 3 — `Serialized*` bridges)
+
+- `org.apache.juneau.serializer.{Serializer, SerializerSession,
SerializeException, SchemaValidationException}`
+- `org.apache.juneau.oapi.OpenApiSerializer`
+- `org.apache.juneau.urlencoding.UrlEncodingSerializer`
+
+Rest-common consumers: `SerializedHeader`, `SerializedPart`,
`SerializedEntity`, `HttpHeaders`, `HttpEntities`.
+
+### C. `InvalidAnnotationException`
-## Phase 3 — Extract `Serialized*` bridge classes
+- Lives in `org.apache.juneau.annotation` (marshall).
+- Used by `httppart/bean/MethodInfoUtils` and `httppart/bean/ResponseBeanMeta`
(static import).
+- Only base class tying it to marshall is the legacy
`org.apache.juneau.BasicRuntimeException` shim, which itself just extends
`org.apache.juneau.commons.BasicRuntimeException`.
-**Difficulty:** Medium
-**Impact:** `SerializedHeader`, `SerializedPart`, `SerializedEntity` + factory
helpers
+### D. Javadoc-only marshall imports
-Heaviest marshall usage (`httppart`, `oapi`, `serializer`, `urlencoding`).
Options:
+Real imports, but only used inside `{@link ...}` comments:
-1. Move bridge types into **marshall**
-2. New **`juneau-rest-bridge`** module between commons and marshall
-3. Keep in rest-common with optional/reflection loading
+- `Content.java` — `import org.apache.juneau.json.JsonSchemaSerializer;`
+- `BasicMediaTypeHeader.java` — `import org.apache.juneau.json.*;`
(`JsonSerializer`) and `import org.apache.juneau.json5.Json5Serializer;`
-**Recommendation:** Move `SerializedHeader` / `SerializedPart` /
`SerializedEntity` (and factories on `HttpHeaders` / `HttpParts` /
`HttpEntities`) to marshall or a bridge module; keep `Basic*` types
serializer-free in rest-common.
+### E. `ClassMeta` (cross-cutting)
+
+`ClassMeta<?>` (in `org.apache.juneau`, marshall) is referenced by:
+
+- `http/HttpParts` (`HEADER_NAME_FUNCTION`, `QUERY_NAME_FUNCTION`, `getName`,
`isHttpPart`, …)
+- `httppart/bean/RequestBeanMeta.getBeanInfo()` / `cm` field
+- `httppart/bean/ResponseBeanMeta.getBeanInfo()` / `cm` field
+
+Removing this dependency depends on **TODO-30** (moving `ClassMeta` and
related non-marshalling type metadata into `juneau-commons`). Rest-common
cannot fully drop marshall until either `ClassMeta` moves (preferred) or these
APIs are reworked to use `ClassInfo` + helpers that already exist in commons.
---
-## Phase 4 — Remove remaining marshall dependencies
+## Plan
+
+### Step 1 — Quick wins (no semantic moves)
+
+**Difficulty:** Trivial. **Removes 0 marshall types but removes some
javadoc-coupled imports.**
+
+1. In `Content.java`, replace `import
org.apache.juneau.json.JsonSchemaSerializer;` + `{@link JsonSchemaSerializer}`
with fully-qualified `{@link org.apache.juneau.json.JsonSchemaSerializer}`.
+2. In `BasicMediaTypeHeader.java`, replace `import org.apache.juneau.json.*;`
and `import org.apache.juneau.json5.Json5Serializer;` with fully-qualified
Javadoc `{@link ...}` references.
+
+Net effect: eliminates the only two marshall imports that exist solely for
Javadoc.
+
+### Step 2 — Move `InvalidAnnotationException` to commons
+
+**Difficulty:** Low.
+
+1. Add `org.apache.juneau.commons.annotation.InvalidAnnotationException`
extending `org.apache.juneau.commons.BasicRuntimeException` (parent of the
marshall shim).
+2. Make the existing `org.apache.juneau.annotation.InvalidAnnotationException`
a deprecated subclass of the commons version for backwards compatibility
(mirrors the existing pattern used for `BasicRuntimeException`).
+3. Repoint `httppart/bean/MethodInfoUtils` and
`httppart/bean/ResponseBeanMeta` at the commons class.
+
+After this, rest-common no longer imports
`org.apache.juneau.annotation.InvalidAnnotationException`.
+
+### Step 3 — Phase 2 follow-through: move `HttpPartSchema` (+ part marshalling
surface) to commons
+
+**Difficulty:** Medium. Single largest item.
+
+Goal: move the **interfaces and the schema data type**, keep the **default
serializer/parser implementations** in marshall.
+
+Move into `org.apache.juneau.commons.httppart`:
+
+- `HttpPartSchema` (+ `Builder`)
+- `HttpPart` interface
+- `HttpPartSerializer` / `HttpPartSerializerSession` interfaces (Creator
inner-classes optional — they can stay in marshall as long as the interface is
in commons)
+- `HttpPartParser` / `HttpPartParserSession` interfaces
+- `HttpPartMarshalling` (annotation + facade)
+
+Known blockers / hand-offs (still applicable from the previous plan revision):
+
+- `apply(HttpPartMarshalling)` on the builder ties to marshall's
`HttpPartMarshalling` annotation handling → move the annotation type to commons
or split apply logic.
+- References to `*Annotation.empty()` (`ItemsAnnotation.DEFAULT`,
`SubItemsAnnotation.DEFAULT`) → already covered by Phase 1b annotation moves;
verify no marshall-only annotations remain.
+- `ParseException` import from marshall in schema-validation paths → either
move a minimal exception to commons or replace with `SchemaValidationException`
(already in commons).
+
+> The concrete implementations (`SimplePartSerializer/Parser`,
`BaseHttpPartSerializer/Parser`, OpenAPI- / URL-encoded-backed serializers,
etc.) stay in marshall and `implement` the commons-side interfaces.
+
+### Step 4 — Phase 3: handle `Serialized*` bridge types
+
+**Difficulty:** Medium. **Impact:** `SerializedHeader`, `SerializedPart`,
`SerializedEntity` + factories on `HttpHeaders` / `HttpParts` / `HttpEntities`.
+
+These types intrinsically need access to `Serializer` / `SerializerSession` /
`OpenApiSerializer` / `UrlEncodingSerializer`, so they cannot live in
rest-common once it stops depending on marshall. Options (pick one):
+
+1. **Move bridges to marshall** — `Serialized*` types move out of
`org.apache.juneau.http.{header,part,entity}` (rest-common) into a marshall
package. `Basic*` types (without serializers) stay in rest-common. Factories on
`HttpHeaders` / `HttpEntities` / `HttpParts` either move with them or get split
(rest-common keeps the no-serializer overloads; serializer-aware overloads move
to marshall).
+2. **New `juneau-rest-bridge` module** between commons and marshall hosting
`Serialized*` types.
+3. **Keep in rest-common with optional/reflective loading.** Not recommended —
defeats the goal.
+
+**Recommendation:** Option 1 — move `Serialized*` (and the serializer-aware
factory overloads) into marshall under `org.apache.juneau.httppart.bridge` (or
similar), keep the non-serializer Basic surface in rest-common.
+
+### Step 5 — Resolve `ClassMeta` references
+
+**Blocked on TODO-30** (`ClassMeta` → commons feasibility pass).
+
+Two paths once TODO-30 lands:
+
+- **(A) `ClassMeta` moves to commons** — rest-common keeps `getBeanInfo()` /
`ClassMeta<?>` surface unchanged.
+- **(B) `ClassMeta` stays in marshall** — rewrite `HttpParts` helpers,
`RequestBeanMeta.getBeanInfo()`, `ResponseBeanMeta.getBeanInfo()` to expose
`ClassInfo` (already in commons) plus an annotation-driven helper, removing the
`ClassMeta` surface from rest-common.
+
+This is the **final blocker** before rest-common can drop marshall from its
pom.
-**Difficulty:** Low–medium
+### Step 6 — Pom + Eclipse `.classpath` flip
-- **BeanCreator** (`httppart.bean`) — `RequestBeanMeta` / `ResponseBeanMeta`;
consider `ClassInfo.newInstance()` or moving `BeanCreator` to commons
-- **Assertions** — rest-common should depend on **`juneau-assertions`**
directly, not only transitively through marshall
+Once steps 1-5 are merged:
-> SVL (`VarResolverSession`) was moved to `juneau-commons` as part of TODO-14
— `HeaderList` / `PartList` no longer pull in marshall for variable resolution.
+- Remove `juneau-marshall` from `juneau-rest-common/pom.xml`.
+- Drop the corresponding `<classpathentry>` from
`juneau-rest-common/.classpath`.
+- Re-run `mvn -pl juneau-rest-common -am clean install` to confirm rest-common
compiles against commons + assertions + httpcore only.
+- Re-run reactor tests; rest-client / rest-server / rest-mock keep marshall.
---
-## Dependency surface (pending rows)
+## Dependency surface (pending rows only)
| Priority | Area | Target |
|----------|------|--------|
-| 3 | `HttpPartSchema` + remaining httppart surface | commons (blocked as
above) |
-| 4 | `Serialized*` bridge | marshall or bridge module |
-| 5 | `BeanCreator`, assertions wiring | commons / optional / direct deps |
+| 1 | Javadoc-only `json.*` imports in `Content.java` /
`BasicMediaTypeHeader.java` | inline fully-qualified `{@link}` |
+| 2 | `InvalidAnnotationException` | commons
(`org.apache.juneau.commons.annotation`) |
+| 3 | `HttpPartSchema` + httppart marshalling **interfaces** | commons
(`org.apache.juneau.commons.httppart`) |
+| 4 | `Serialized*` bridges (+ factory overloads) | marshall (or new
`juneau-rest-bridge` module) |
+| 5 | `ClassMeta<?>` surface in `HttpParts` / `*BeanMeta` | depends on TODO-30
outcome |
+| 6 | Drop `juneau-marshall` dep from rest-common pom + `.classpath` |
rest-common build |
---
-## Risk notes (still relevant)
+## Risk notes
-- Split-package / HTTP types in `org.apache.juneau.commons.http`
-- Binary compatibility on moves
-- `@Schema` / serializer integration complexity
-- **`@XApply` split** (`on` / `onClass`) is a separate, release-sized effort
if pursued
-- Keep phases independently buildable
+- **Split-package risk** — `org.apache.juneau.httppart` exists in both
marshall (concrete impls) and commons (enums + interfaces). OSGi consumers will
see split packages; this is already the case for
`org.apache.juneau.commons.httppart` vs `org.apache.juneau.httppart`. Keep
using the **`org.apache.juneau.commons.httppart`** namespace for moved
interfaces to avoid worsening the split.
+- **Binary compatibility** — Steps 2 and 3 must leave deprecated shims in
`org.apache.juneau.annotation.InvalidAnnotationException` and
`org.apache.juneau.httppart.HttpPartSchema` (etc.) extending / type-aliasing
the commons versions for at least one release.
+- **`@Schema` ↔ serializer integration** — the schema-aware OpenAPI /
URL-encoding serializer paths in marshall must continue to wire through the
commons-side `HttpPartSchema` after the move; verify via existing
schema-validation tests.
+- **`@XApply` split** (`on` / `onClass`) is a separate, release-sized effort —
out of scope here.
+- **Keep phases independently buildable** — each Step above should be its own
commit / PR; the reactor must build green between steps.
diff --git a/todo/TODO.md b/todo/TODO.md
index 65e8153ee5..50aaada8bc 100644
--- a/todo/TODO.md
+++ b/todo/TODO.md
@@ -7,8 +7,6 @@
- [TODO-4] Duration.ofDays(7) serialized in hours?
-- [TODO-6] Add an `ai` / `shortDescription` field to `@Schema` (and related
annotations) for concise LLM/AI-consumption descriptions that stay under token
budgets. See `todo/TODO-6-ai-short-description.md`.
-
- [TODO-7] Decouple `juneau-rest-common` from `juneau-marshall` by breaking
the compile dependency so REST annotations and beans can be used without
pulling in the full serialization stack. See
`todo/TODO-7-decouple-rest-common-from-marshall.md`.
- [TODO-9] Fix remaining skipped Markdown round-trip test cases (tables,
nested structures, edge cases). See `todo/TODO-9-markdown-remaining-issues.md`.
@@ -25,3 +23,5 @@
- [TODO-30] Investigate moving `ClassMeta` and related non-marshalling type
metadata from `juneau-marshall` into `juneau-commons` (analysis/feasibility
pass). See `todo/TODO-30-classmeta-to-commons.md`.
+- [TODO-34] Come up with a plan to generate information about Juneau in a
format that's easy for AI agents to consume.
+
