spring-projects / spring-projects/spring-ai
`@Schema` constraints silently ignored on method parameters
Nobody has claimed this yet.
- Dominant language
- Java
- Stars
- 9.5k
- Forks
- 2.9k
- Avg merge
- 1d 10h
- Merged PRs (30d)
- 5
Description
Bug description
@Schema constraint attributes (minimum, maximum, allowableValues, pattern, example) are silently ignored when placed on @Tool method parameters. Only description and requiredMode/required are read from parameter-level @Schema annotations. The constraints are absent from the generated JSON schema with no error or warning.
Environment
- Spring AI version: 1.1.4
- Java version: 21
Steps to reproduce
- Annotate a
@Toolmethod parameter with@Schemaconstraints:
@Service
public class ChanceTool {
@Tool(name = "set_chance", description = "Set the chance value")
public String setChance(
@Schema(description = "Chance percentage", minimum = "0", maximum = "100")
int chance
) {
return "Chance set to " + chance + "%";
}
}
-
Inspect the generated input schema (e.g. via
tools/listMCP call or by callingJsonSchemaGenerator.generateForMethodInputdirectly). -
Observe that
minimumandmaximumare absent from thechanceproperty.
Expected behavior
The generated schema for chance should include the constraints:
{
"properties": {
"chance": {
"type": "integer",
"description": "Chance percentage",
"minimum": 0,
"maximum": 100
}
},
"required": ["chance"]
}
Minimal Complete Reproducible example
import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import io.swagger.v3.oas.annotations.media.Schema;
import org.junit.jupiter.api.Test;
import org.springframework.ai.util.json.schema.JsonSchemaGenerator;
import java.lang.reflect.Method;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertEquals;
class JsonSchemaGeneratorParameterSchemaTest {
static class ChanceTool {
public String setChance(
@Schema(description = "Chance percentage", minimum = "0", maximum = "100")
int chance
) {
return "Chance set to " + chance + "%";
}
}
@Test
void schemaConstraintsOnMethodParametersAreReflectedInGeneratedSchema() throws Exception {
Method method = ChanceTool.class.getDeclaredMethod("setChance", int.class);
String schema = JsonSchemaGenerator.generateForMethodInput(method);
JsonNode chanceNode = new ObjectMapper().readTree(schema).get("properties").get("chance");
// description is correctly picked up
assertEquals("Chance percentage", chanceNode.get("description").asText());
// These fail, minimum and maximum are absent from the generated schema
assertNotNull(chanceNode.get("minimum"), "expected 'minimum' in schema but was absent");
assertNotNull(chanceNode.get("maximum"), "expected 'maximum' in schema but was absent");
}
}
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with JsonSchemaGenerator.generateForMethodInput and the provided JsonSchemaGeneratorParameterSchemaTest, then trace how parameter-level @Schema annotations are converted into the generated JSON schema. Done means the test verifies minimum and maximum, with the other listed constraint attributes represented as applicable.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- java, spring
- Domain
- api, backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 72/100