spring-projects / spring-projects/spring-ai

`@Schema` constraints silently ignored on method parameters

Open
#5,803 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

status: waiting-for-triage
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

  1. Annotate a @Tool method parameter with @Schema constraints:
@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 + "%";
    }
}
  1. Inspect the generated input schema (e.g. via tools/list MCP call or by calling JsonSchemaGenerator.generateForMethodInput directly).

  2. Observe that minimum and maximum are absent from the chance property.

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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.