java: add schema attribute to @CopilotToolParam for custom type schema override

[rinceyuan]

Closes #1794
Superseded by #2069

Summary

Adds an optional schema attribute to @CopilotToolParam that allows users to explicitly specify the JSON Schema for a tool parameter. This enables support for custom/third-party types that the SchemaGenerator cannot automatically map.

Example

@CopilotTool("Schedule a deployment")
public String scheduleDeployment(
        @CopilotToolParam(value = "Deployment time in ISO-8601",
            schema = "{\"type\":\"string\",\"format\":\"date-time\"}")
        com.acme.internal.AcmeDateTime deployTime) {
    return "Scheduled for " + deployTime;
}

Changes

CopilotToolParam.java

• Added String schema() default "" annotation attribute with Javadoc

CopilotToolProcessor.java

• In generateSchemaWithParamMetadata(): when schema is non-empty, use it instead of auto-generated schema
• Added compile-time validation: schema + defaultValue conflict emits error
• Added compile-time validation: invalid JSON (not starting/ending with braces) emits error
• Added jsonToMapOfSource() — a minimal recursive-descent JSON parser that converts JSON strings to Map.of(...) source code expressions at compile time (no external JSON library needed)

Param.java

• Added schema field, fluent schema() mutator, and getter for lambda API parity
• Updated equals(), hashCode() to include schema

CopilotToolProcessorTest.java (4 new tests)

1. Schema override — custom schema appears in generated code
2. Schema + defaultValue conflict — produces compile error
3. Invalid JSON — produces compile error
4. Empty schema — falls through to normal type-based generation

Testing

• All 4 new tests pass
• The only failing test (generatesNullMetadata_whenAbsent) is a pre-existing failure on main unrelated to this PR

[rinceyuan]

@microsoft-github-policy-service agree company=Microsoft

[rinceyuan]

@edburns Hi! This implements #1794 (sibling of #1836) — adds schema attribute to @CopilotToolParam for custom type schema overrides. 4 files changed, 4 new tests. Would appreciate your review. Thanks!

[Copilot]

Pull request overview

Adds explicit JSON Schema overrides for Java tool parameters.

Changes:

• Extends annotation and fluent parameter APIs with schema.
• Validates and converts JSON overrides during annotation processing.
• Adds processor tests for basic override and validation paths.

Show a summary per file

File	Description
CopilotToolParam.java	Adds the annotation attribute and Javadoc.
Param.java	Adds fluent schema metadata support.
CopilotToolProcessor.java	Validates and converts schema JSON into generated Java.
CopilotToolProcessorTest.java	Tests basic override behavior and errors.

Review details

• Files reviewed: 4/4 changed files
• Comments generated: 7
• Review effort level: Medium

[edburns]

Review finding: schema override missing from tools-as-lambda path

The PR adds the schema attribute to @CopilotToolParam and the annotation processor correctly uses it to bypass auto-generated schema. It also adds the schema field and fluent setter to Param.java.

However, the tools-as-lambda path (ToolDefinition.from(...) → ParamSchema.buildSchema()) does not consume Param.schema(). In ParamSchema.java line 87, schema generation always calls orType(param.type()) regardless of whether a schema override is set:

java Map<String, Object> typeSchema = forType(param.type());

This means a user who defines a tool inline like:

java ToolDefinition.from("schedule", "Schedule meeting", Param.of(MyCustomDateTime.class, "when", "Meeting time").schema("{\"type\":\"string\",\"format\":\"date-time\"}"), when -> "Scheduled for " + when);

…would still get the auto-derived schema from orType(), not the explicit override.

I am working now to address this gap and will follow up.

[edburns]

Superceded by #2069