Skip to content

Recognize a root $dynamicRef when defaulting an output schema to an object - #649

Merged
koic merged 1 commit into
modelcontextprotocol:mainfrom
koic:recognize_a_root_dynamic_ref_when_defaulting_an_output_schema
Nov 2, 2026
Merged

koic merged 1 commit into
modelcontextprotocol:mainfrom
koic:recognize_a_root_dynamic_ref_when_defaulting_an_output_schema

Conversation

@koic

@koic koic commented Nov 1, 2026

Copy link
Copy Markdown
Member

Motivation and Context

An output schema whose root has none of the keywords in ROOT_SCHEMA_KEYWORDS is defaulted to type: "object", which keeps the wire output of the common properties-only shape while SEP-2106 lets an output schema be any JSON Schema 2020-12 document. That list named $ref but not $dynamicRef, although Tool::Schema already treats both as the reference keywords it restricts to the same document. A schema whose root is a $dynamicRef to an array or a primitive was therefore advertised with an extra type: "object" and rejected its own valid results: with result validation on, tools/call answered -32603 where the same schema written with $ref passed.

The list now takes both reference keywords from Tool::Schema::REFERENCE_KEYWORDS, so the two cannot drift apart again, and the tools page names $dynamicRef among the keywords that keep the default off and beside $ref in the same-document rule, which the code has always applied to both.

Closes #647

How Has This Been Tested?

test/mcp/tool/output_schema_test.rb and test/mcp/server_test.rb. Before the fix, the $dynamicRef root schema gained type: "object" in to_h and in the tools/list entry, validate_result([1, 2]) raised "value at root is not an object", and tools/call answered -32603 "Internal error".

Breaking Changes

None. A schema whose root is a $dynamicRef is now advertised as written; every other root shape is unchanged.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • New and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

…bject

## Motivation and Context

An output schema whose root has none of the keywords in `ROOT_SCHEMA_KEYWORDS` is defaulted to `type: "object"`,
which keeps the wire output of the common `properties`-only shape while SEP-2106 lets an output schema be any JSON
Schema 2020-12 document. That list named `$ref` but not `$dynamicRef`, although `Tool::Schema` already treats both
as the reference keywords it restricts to the same document. A schema whose root is a `$dynamicRef` to an array or
a primitive was therefore advertised with an extra `type: "object"` and rejected its own valid results: with result
validation on, `tools/call` answered -32603 where the same schema written with `$ref` passed.

The list now takes both reference keywords from `Tool::Schema::REFERENCE_KEYWORDS`, so the two cannot drift apart
again, and the tools page names `$dynamicRef` among the keywords that keep the default off and beside `$ref` in
the same-document rule, which the code has always applied to both.

Closes modelcontextprotocol#647

## How Has This Been Tested?

test/mcp/tool/output_schema_test.rb and test/mcp/server_test.rb. Before the fix, the `$dynamicRef` root schema
gained `type: "object"` in `to_h` and in the `tools/list` entry, `validate_result([1, 2])` raised "value at root is
not an object", and `tools/call` answered -32603 "Internal error".

## Breaking Changes

None. A schema whose root is a `$dynamicRef` is now advertised as written; every other root shape is unchanged.
@koic
koic merged commit 8f6a206 into modelcontextprotocol:main Nov 2, 2026
13 checks passed
@koic
koic deleted the recognize_a_root_dynamic_ref_when_defaulting_an_output_schema branch November 2, 2026 14:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Root $dynamicRef output schemas receive an incompatible default object type

2 participants