Query on Input/Output Schema Types and Definition practices ($defs vs. Inline)

[BruceKellan]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

Hello Team,

I have some confusion regarding the new schema features in the java-sdk.

1. Input vs. Output Schema Type

Why is the input schema (when building an McpTool) a JsonSchema type, while the output schema is defined as a Map? For consistency, shouldn't the output schema also be a JsonSchema type?

2. Defining Complex Types This leads to questions on how to define complex types:

For Output Schema (as Map): What is the correct way to define complex/reusable types?
a) Place them in $defs / definitions and use $ref?
b) Nest the definitions directly inline?

For Input Schema (as JsonSchema):
I noticed in spring-ai examples that definitions are sometimes nested inline. Is direct inline nesting also a supported practice for the input schema?

https://github.com/spring-projects/spring-ai/blob/fb523c8fd1713551682e2e71ddd6b09fd66043d4/spring-ai-model/src/test/java/org/springframework/ai/util/json/JsonSchemaGeneratorTests.java#L282C1-L336C3

Summary: Could you clarify the recommended practice for choosing between #/definitions/, #/$defs/, and direct inline nesting for both input and output schemas?