Skip to content

fix(schema): close oneOf type-check bypass and render SEP-2106 Tool examples #3185

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
olaservo wants to merge 5 commits into
base: main
Choose a base branch
from
+52 −42
Open

fix(schema): close oneOf type-check bypass and render SEP-2106 Tool examples #3185

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
ec3efce
fix(schema): close type-check bypass in composition inputSchema example
olaservo Aug 2, 2026
1898711
docs(schema): render SEP-2106 Tool examples in 2026-07-28
olaservo Aug 2, 2026
ddeeb51
docs(schema): note the composition authoring pitfall on inputSchema
olaservo Aug 2, 2026
3671d8d
chore(schema): regenerate schema.json for the inputSchema description
olaservo Aug 2, 2026
7247aae
Merge branch 'main' into fix/composition-example-oneof
olaservo Aug 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions docs/specification/2026-07-28/schema.mdx
View file
Open in desktop

Large diffs are not rendered by default.

7 changes: 5 additions & 2 deletions docs/specification/draft/schema.mdx
View file
Open in desktop

Large diffs are not rendered by default.

27 changes: 9 additions & 18 deletions schema/2026-07-28/examples/Tool/tool-with-composition-input-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,16 @@
"description": "Find a resource by ID or name",
"inputSchema": {
"type": "object",
"oneOf": [
{
"properties": {
"id": {
"type": "string",
"description": "Resource ID"
}
},
"required": ["id"]
"properties": {
"id": {
"type": "string",
"description": "Resource ID"
},
{
"properties": {
"name": {
"type": "string",
"description": "Resource name"
}
},
"required": ["name"]
"name": {
"type": "string",
"description": "Resource name"
}
]
},
"oneOf": [{ "required": ["id"] }, { "required": ["name"] }]
}
}
2 changes: 1 addition & 1 deletion schema/2026-07-28/schema.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions schema/2026-07-28/schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1965,9 +1965,15 @@ export interface ToolAnnotations {
* @example With no parameters
* {@includeCode ./examples/Tool/with-no-parameters.json}
*
* @example With a composition input schema
* {@includeCode ./examples/Tool/tool-with-composition-input-schema.json}
*
* @example With output schema for structured content
* {@includeCode ./examples/Tool/with-output-schema-for-structured-content.json}
*
* @example With an array output schema
* {@includeCode ./examples/Tool/tool-with-array-output-schema.json}
Comment thread
olaservo marked this conversation as resolved.
*
* @category `tools/list`
*/
export interface Tool extends BaseMetadata, Icons {
Expand All @@ -1987,6 +1993,11 @@ export interface Tool extends BaseMetadata, Icons {
* (`if`/`then`/`else`), reference keywords (`$ref`, `$defs`, `$anchor`), and any other
* standard validation or annotation keywords.
*
* When using composition keywords, declare `properties` at the schema root and keep the
* branches to presence assertions such as `required`. A subschema that fails on a type
* error is indistinguishable from one that does not apply, so type constraints placed
* inside `oneOf` branches are not enforced for whichever branch does not match.
*
* Property schemas may carry an `x-mcp-header` annotation to mirror the
* argument value into an HTTP header on the Streamable HTTP transport. See
* the Streamable HTTP transport specification for the validity and
Expand Down
27 changes: 9 additions & 18 deletions schema/draft/examples/Tool/tool-with-composition-input-schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,25 +4,16 @@
"description": "Find a resource by ID or name",
"inputSchema": {
"type": "object",
"oneOf": [
{
"properties": {
"id": {
"type": "string",
"description": "Resource ID"
}
},
"required": ["id"]
"properties": {
"id": {
"type": "string",
"description": "Resource ID"
},
{
"properties": {
"name": {
"type": "string",
"description": "Resource name"
}
},
"required": ["name"]
"name": {
"type": "string",
"description": "Resource name"
}
]
},
"oneOf": [{ "required": ["id"] }, { "required": ["name"] }]
}
}
2 changes: 1 addition & 1 deletion schema/draft/schema.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

11 changes: 11 additions & 0 deletions schema/draft/schema.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1965,9 +1965,15 @@ export interface ToolAnnotations {
* @example With no parameters
* {@includeCode ./examples/Tool/with-no-parameters.json}
*
* @example With a composition input schema
* {@includeCode ./examples/Tool/tool-with-composition-input-schema.json}
*
* @example With output schema for structured content
* {@includeCode ./examples/Tool/with-output-schema-for-structured-content.json}
*
* @example With an array output schema
* {@includeCode ./examples/Tool/tool-with-array-output-schema.json}
Comment thread
olaservo marked this conversation as resolved.
*
* @category `tools/list`
*/
export interface Tool extends BaseMetadata, Icons {
Expand All @@ -1987,6 +1993,11 @@ export interface Tool extends BaseMetadata, Icons {
* (`if`/`then`/`else`), reference keywords (`$ref`, `$defs`, `$anchor`), and any other
* standard validation or annotation keywords.
*
* When using composition keywords, declare `properties` at the schema root and keep the
* branches to presence assertions such as `required`. A subschema that fails on a type
* error is indistinguishable from one that does not apply, so type constraints placed
* inside `oneOf` branches are not enforced for whichever branch does not match.
*
* Property schemas may carry an `x-mcp-header` annotation to mirror the
* argument value into an HTTP header on the Streamable HTTP transport. See
* the Streamable HTTP transport specification for the validity and
Expand Down
Loading