Consolidate JSON Schema generation documentation between Tool Calling and Structured Output#6160
Consolidate JSON Schema generation documentation between Tool Calling and Structured Output#6160ChoMinGi wants to merge 3 commits into
Conversation
…entation - Add JSON Schema Customization section to structured-output/converters.adoc - Add cross-reference from tools.adoc to structured-output/converters.adoc spring-projects#5915 Signed-off-by: Mingi Cho <81455273+ChoMinGi@users.noreply.github.com>
|
|
||
| * `@JsonProperty(required = false)` — Jackson | ||
| * `@Schema(required = false)` — Swagger | ||
| * `@Nullable` — Spring Framework / JSpecify |
There was a problem hiding this comment.
Spring Framework's one is deprecated, so I would recommend not highlighting it. Please note that Jakarta Annotations' one is a viable alternative for this use case, it may be interesting to mention it as well.
There was a problem hiding this comment.
Good catch, thanks! Fixed — the bullet now reads @Nullable — JSpecify / Jakarta Annotations. Both are honored via org.springframework.core.Nullness, and I verified the Jakarta one with a runtime test. I applied the same fix to the original list in tools.adoc that this section was consolidated from, so the two documents stay consistent.
While verifying, I found and fixed a few more inaccuracies in the same lists: @Schema(required = false) never actually makes a property optional (RequiredMode.AUTO is treated as required), so both lists now use @Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED) — matching the tests and your #6541 examples; the Jackson description bullets used a non-existent description attribute; and the precedence claim is now limited to method parameters, since victools ORs required checks across modules for bean properties.
…ON schema docs - Attribute `@Nullable` to JSpecify / Jakarta Annotations instead of the deprecated Spring Framework annotation - Replace `@Schema(required = false)` with `@Schema(requiredMode = Schema.RequiredMode.NOT_REQUIRED)`; the deprecated `required` attribute alone never makes a property optional because `RequiredMode.AUTO` is treated as required - Fix the `@JsonClassDescription`/`@JsonPropertyDescription` bullets to use their actual `value` attribute; `description = ...` does not compile - Drop the strict precedence claim for bean properties; victools combines required checks across modules, so precedence only holds for method parameters - Soften the `@ToolParam` note; it is also honored on bean fields spring-projects#5915 Signed-off-by: Mingi Cho <81455273+ChoMinGi@users.noreply.github.com>
…arameters in tools.adoc - Qualify the description-precedence note to a tool method's own parameters; on bean properties Jackson's description wins, not @ToolParam - Remove the @JsonClassDescription bullet from the parameter list; it targets types, cannot be applied to a parameter, and is never read on that path - Qualify the required-precedence claim the same way; for bean properties and nested parameter types the module checks are OR-combined, matching converters.adoc spring-projects#5915 Signed-off-by: Mingi Cho <81455273+ChoMinGi@users.noreply.github.com>
3 participants
Fixes #5915
Following the consolidation in #5897,
BeanOutputConverternow delegates toJsonSchemaGeneratorfor schema generation, aligning the behavior between tool calling and structured output conversion.However, the documentation for these two features remained separate — the supported annotations and default required-property behavior were only documented in the Tool Calling page.
structured-output-converter.adocdocumenting the supported annotations for description (@JsonClassDescription,@JsonPropertyDescription,@Schema) and required/optional status (@JsonProperty,@Schema,@Nullable)tools.adoctostructured-output-converter.adoc, noting thatBeanOutputConvertershares the sameJsonSchemaGenerator