Clarify tool `parameters` JSON Schema validation behavior (depth, location, failure mode)
- 主要语言
- Java
- 星标
- 10.5k
- 派生
- 1.5k
- 平均合并
- 1 天 14 小时
- 30 天内合并 PR
- 129
描述
### Summary
Where does tool `parameters` JSON Schema validation happen, and how deep does it go? This affects consumer architecture decisions for typed tools that aim to use the schema as the source of truth for input correctness.
### Specific questions
1. **Where does validation happen?** The Node SDK (`nodejs/src/client.ts`) passes `parameters` verbatim to RPC — no client-side validation, no JSON Schema validator imported. Validation, if any, must happen in the CLI binary or at the model layer. **Where exactly?**
2. **How deep does it go?** For a schema like:
```json
{
"type": "object",
"required": ["topIssues", "summary"],
"additionalProperties": false,
"properties": {
"topIssues": {
"type": "array",
"items": { "type": "object", "required": ["issueId", "severity"], "properties": {} }
},
"summary": { "type": "string" }
}
}
```
Does the runtime reject:
- Wrong top-level key? (`{top_issues: [...]}` instead of `{topIssues: [...]}`)
- Missing top-level required field? (`{topIssues: [...]}` missing `summary`)
- Extra top-level key when `additionalProperties: false`?
- **Wrong item-level shape?** (`topIssues: [{title: "foo"}]` — missing required `issueId` and `severity`)
- Wrong nested type?
3. **What happens on failure?** Does the orchestrator get re-prompted with the validation error so it can self-correct? Or does the tool call just fail silently? The `TaskCompleteData.success` field has a comment "False when validation failed (e.g., invalid arguments)" suggesting validation surfaces somewhere, but the consumer-visible behavior isn't documented.
### Why this matters
Consumers migrating from generic `writeArtifact({path, content: "..."})` patterns to typed tools depend on what the boundary enforces. If item-level shape IS validated, the LLM physically cannot return a malformed inner structure. If it isn't, handler-side item-level checks remain necessary and the "typed tool" claim is partial.
For us specifically: we have ~6 LLM-driven agents currently writing terminal artifacts through a generic `writeArtifact` shape, with schema living only in the prompt. We see ~30-40% drift to wrong shapes (snake_case vs camelCase, renamed wrappers, etc.) which costs $15-30 per wasted phase. Migrating to typed phase tools is on the roadmap; the value of that migration depends on the answers above.
### Evidence (SDK source — partial answer)
`nodejs/src/client.ts`: tool parameters are converted via `toJsonSchema()` (which calls `parameters.toJSONSchema()` for Zod schemas or passes JSON Schema objects through unchanged). No client-side validation. No JSON Schema validator (ajv, zod-validate, etc.) is imported.
**Confirmed:** the Node SDK does no validation. Validation, if any, is entirely in the CLI binary (which is not source-readable).
### What we'd like
A docs page or release note clarifying: (a) where validation happens (SDK / CLI / model layer), (b) what shape it covers (top-level only / item-level / arbitrarily deep), (c) what happens on failure (re-prompt / silent / error).
If item-level isn't validated today, that promotes this from a question to a feature request: **deep JSON Schema enforcement against `parameters`**.
### Environment
```
- SDK: @github/copilot-sdk@0.3.0
- CLI: @github/copilot@1.0.45
- Node: 22 LTS
- OS: Windows 11
- Model: claude-sonnet-4-6
```
贡献指南
调研方向
从 nodejs/src/client.ts 开始,跟踪参数是如何转换并传递给 RPC 的;查看 TaskCompleteData.success 的注释,将其作为已记录的失败线索。验证 CLI 或模型层对嵌套验证和失败的行为,然后在文档页面或发布说明中记录验证位置、验证深度以及消费者可见的结果。
由索引模型根据 Issue 内容生成。
评估
- 技术栈
- nodejs
- 领域
- api, documentation
- Issue 类型
- 文档
- 难度
- 4/5
- 预计耗时
- 3-5 天
- 活跃度
- 冷清
- 描述清晰度
- 基本清楚
- 新手友好度
- 45/100