Skip to content

fix: Remove JsonSchema and use a Map for inputSchema to support json schemas dialect - #749

Merged
Kehrlann merged 9 commits into
modelcontextprotocol:mainfrom
bilaloumehdi:fix/json-schema-spec-support
Apr 10, 2026
Merged

fix: Remove JsonSchema and use a Map for inputSchema to support json schemas dialect#749
Kehrlann merged 9 commits into
modelcontextprotocol:mainfrom
bilaloumehdi:fix/json-schema-spec-support

Conversation

@bilaloumehdi

@bilaloumehdi bilaloumehdi commented Jan 14, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Following the Model Context Protocol specification for JSON schemas usage, the schema should, by default follow the 2020-12 dialect: json-schema-2020-12 if no $schema specified.

Motivation and Context

The need for this change arose from the requirement for a tool that can handle one of two properties objects. This can be achieved by defining an inputSchema with oneOf at the top level, for example:

 inputSchema: { 
  type: object, 
  oneOf: [ 
    { properties: {}, required: ["test"] },
    { properties: {}, required: ["test", "command"] }
  ] 
}

The current state

The schema is currently deserialized to a JsonSchema record and ignores oneOf at the top level. A specific fix for this issue would be to add a new field to the JsonSchema record for oneOf; however, this approach does not scale well if additional top-level entries (such as allOf) are needed. This PR shifts to using a Map<String, Object> to deserialize the inputSchema

Next Steps and improvements

I suggest adding validation for schemas based on the schema specifications from the SDK, not only checking for serialization errors. This would help fail fast and provide feedback about any issues in the defined schemas.

How Has This Been Tested?

Existing Tests have been adjusted for these changes, and a new test has been introduced with json schemas that have oneOf at the top level to verify that deserialization do not ignore it.

Breaking Changes

Users would need to change the tool's inputSchema data type

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

Additional context

@bilaloumehdi bilaloumehdi changed the title fix: remove JsonSchema an use a Map for inputSchema to support json schema specs fix: remove JsonSchema and use a Map for inputSchema to support json schema specs Jan 14, 2026
@bilaloumehdi bilaloumehdi changed the title fix: remove JsonSchema and use a Map for inputSchema to support json schema specs fix: Remove JsonSchema and use a Map for inputSchema to support json schema specs Jan 14, 2026
@bilaloumehdi bilaloumehdi changed the title fix: Remove JsonSchema and use a Map for inputSchema to support json schema specs fix: Remove JsonSchema and use a Map for inputSchema to support json schemas dialect Jan 14, 2026
@tzolov tzolov added area/mcp-schema P1 Significant bug affecting many users, highly requested feature breaking-change labels Mar 2, 2026
@joaquinescalante23 joaquinescalante23 mentioned this pull request Mar 4, 2026
Open
@bilaloumehdi

bilaloumehdi commented Mar 9, 2026

Copy link
Copy Markdown
Contributor Author

@tzolov conflicts have been resolved

@tzolov tzolov mentioned this pull request Apr 2, 2026
Closed
@Kehrlann Kehrlann mentioned this pull request Apr 2, 2026
Merged
Kehrlann
Kehrlann requested changes Apr 3, 2026
View reviewed changes

@Kehrlann Kehrlann left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your contribution!

I'd like to make the transition path smoother, by keeping the JsonSchema type around.

Comment thread mcp-core/src/test/java/io/modelcontextprotocol/util/ToolsUtils.java
Comment thread mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
Comment thread mcp-core/src/main/java/io/modelcontextprotocol/spec/McpSchema.java
Comment thread mcp-test/src/main/java/io/modelcontextprotocol/util/ToolsUtils.java
Comment thread mcp-test/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java Outdated
Comment thread mcp-test/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java Outdated
@Kehrlann Kehrlann self-assigned this Apr 3, 2026
@Kehrlann
polish modelcontextprotocolgh-749
52b5642 
Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>
Kehrlann
Kehrlann approved these changes Apr 10, 2026
View reviewed changes

@Kehrlann Kehrlann left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Implemented changes.

@Kehrlann
Kehrlann merged commit 9520323 into modelcontextprotocol:main Apr 10, 2026
21 checks passed
ashakirin pushed a commit to ashakirin/java-sdk that referenced this pull request Apr 10, 2026
@bilaloumehdi @Kehrlann @ashakirin
fix: Remove JsonSchema and use a Map for inputSchema to support json …
e8bd7e8 
…schemas dialect (modelcontextprotocol#749)

* feat: remove JsonSchema an use a Map for inputSchema

- Fixes modelcontextprotocol#886

Co-authored-by: Daniel Garnier-Moiroux <git@garnier.wf>
@danielvolovik96 danielvolovik96 mentioned this pull request Apr 26, 2026
Closed
@DragonFSKY DragonFSKY mentioned this pull request May 21, 2026
Open
JohannesLichtenberger pushed a commit to sirixdb/sirix that referenced this pull request Jul 27, 2026
@claude
Adapt sirix-mcp to the MCP SDK 2.0 input-schema change
2db0248 
The SDK dropped its JsonSchema record in 2.0 so that a tool's inputSchema
can carry any JSON Schema dialect rather than the subset that record could
express (modelcontextprotocol/java-sdk#749), which is what broke the
Dependabot bump in #1144:

  SirixMcpServer.java:256: error: incompatible types:
      JsonSchema cannot be converted to Map<String,Object>

The schema helper now builds the document as a plain map, and "required"
is omitted rather than emitted empty for the one tool that takes no
arguments. The test's local copy of the helper gets the same treatment.

Nothing else in the 2.0 breaking-change list applies here: sirix-mcp is
stdio-only, so the SSE deprecation and the transport-builder removals do
not reach it, and the rest of the surface it uses is unchanged.

Worth knowing before editing any of the fourteen schemas: since 2.0 the
SDK validates this document against the 2020-12 meta-schema at
registration time and validates incoming tool arguments against it, so a
"required" naming a property that "properties" does not declare is now
rejected rather than ignored. That is documented on the helper.

Verified by reproducing the failure against 2.0.0 first, then fixing:
sirix-mcp is 47 tests across 6 classes, 0 skipped, 0 failures, including
McpServerE2ETest, which registers all 13 tools through the real SDK and
runs full tool-call pipelines -- so registration-time schema validation
and call-time argument validation both accept the new shape.

Note that McpServerE2ETest carries its own copy of the tool registration
rather than calling SirixMcpServer's, so that module's own fourteen call
sites are compile-checked only. Both copies now use the identical shape.
JohannesLichtenberger pushed a commit to sirixdb/sirix that referenced this pull request Jul 28, 2026
@claude
Adapt sirix-mcp to the MCP SDK 2.0 input-schema change
8f90908 
The SDK dropped its JsonSchema record in 2.0 so that a tool's inputSchema
can carry any JSON Schema dialect rather than the subset that record could
express (modelcontextprotocol/java-sdk#749), which is what broke the
Dependabot bump in #1144:

  SirixMcpServer.java:256: error: incompatible types:
      JsonSchema cannot be converted to Map<String,Object>

The schema helper now builds the document as a plain map, and "required"
is omitted rather than emitted empty for the one tool that takes no
arguments. The test's local copy of the helper gets the same treatment.

Nothing else in the 2.0 breaking-change list applies here: sirix-mcp is
stdio-only, so the SSE deprecation and the transport-builder removals do
not reach it, and the rest of the surface it uses is unchanged.

Worth knowing before editing any of the fourteen schemas: since 2.0 the
SDK validates this document against the 2020-12 meta-schema at
registration time and validates incoming tool arguments against it, so a
"required" naming a property that "properties" does not declare is now
rejected rather than ignored. That is documented on the helper.

Verified by reproducing the failure against 2.0.0 first, then fixing:
sirix-mcp is 47 tests across 6 classes, 0 skipped, 0 failures, including
McpServerE2ETest, which registers all 13 tools through the real SDK and
runs full tool-call pipelines -- so registration-time schema validation
and call-time argument validation both accept the new shape.

Note that McpServerE2ETest carries its own copy of the tool registration
rather than calling SirixMcpServer's, so that module's own fourteen call
sites are compile-checked only. Both copies now use the identical shape.
@JohannesLichtenberger JohannesLichtenberger mentioned this pull request Jul 28, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Kehrlann Kehrlann Kehrlann approved these changes

Assignees

@Kehrlann Kehrlann

Labels

area/mcp-schema breaking-change P1 Significant bug affecting many users, highly requested feature

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@bilaloumehdi @Kehrlann @tzolov