Consistent JSON forward/backward compatibility (2.0 foundation) by chemicL · Pull Request #927 · modelcontextprotocol/java-sdk

chemicL · 2026-04-20T16:39:14Z

Motivation and Context

The MCP specification evolves continuously; domain types must absorb
new fields and subtypes without breaking existing clients or servers.
On the 1.x line this is structurally prevented by sealed interfaces,
which make it impossible to add a permitted subtype without breaking
exhaustive pattern-match switch expressions in caller code. This
commit opens the 2.0 release line, where those constraints are lifted
and serialization is made self-contained — independent of any global
ObjectMapper configuration.

Breaking Changes

Breaking changes for users migrating from 1.x

Sealed interfaces removed from JSONRPCMessage, Request, Result,
Notification, ResourceContents, CompleteReference and Content.
Exhaustive switch expressions over these types must add a default
branch.
Prompt(name, description, null) no longer silently coerces null
arguments to an empty list. Use Prompt.withDefaults() to preserve
the previous behaviour.
CompleteCompletion.total and .hasMore are now absent from the wire
when not set, rather than being emitted as null.
ServerParameters no longer carries Jackson annotations; it is an
internal configuration class, not a wire type.

What now works that did not before

CompleteReference polymorphic dispatch (PromptReference vs
ResourceReference) works through a plain readValue or convertValue
call — no hand-rolled map inspection required.
LoggingLevel deserialization is lenient: unknown level strings
produce null instead of throwing.
All domain records now tolerate unknown JSON fields, so a client
built against an older SDK version will not fail when a newer server
sends fields it does not yet recognise.
Null optional fields are consistently absent from serialized output
regardless of ObjectMapper configuration.

Documentation

CONTRIBUTING adds an "Evolving wire-serialized records" section: a
9-rule recipe and example for adding a field safely.
MIGRATION-2.0 documents all breaking changes listed above.

Follow-up coming next

Several spec-required fields (e.g. JSONRPCError.code/message,
ProgressNotification.progress, CreateMessageRequest.maxTokens,
CallToolResult.content) are stored as nullable Java types without a
null guard. If constructed with null, the NON_ABSENT rule silently
omits them, producing invalid wire JSON without throwing. Fix: compact
canonical constructors with Assert.notNull, following the pattern
already in JSONRPCRequest.

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

The MCP specification evolves continuously; domain types must absorb new fields and subtypes without breaking existing clients or servers. On the 1.x line this is structurally prevented by sealed interfaces, which make it impossible to add a permitted subtype without breaking exhaustive pattern-match switch expressions in caller code. This commit opens the 2.0 release line, where those constraints are lifted and serialization is made self-contained — independent of any global ObjectMapper configuration. Breaking changes for users migrating from 1.x - Sealed interfaces removed from JSONRPCMessage, Request, Result, Notification, ResourceContents, CompleteReference and Content. Exhaustive switch expressions over these types must add a default branch. - Prompt(name, description, null) no longer silently coerces null arguments to an empty list. Use Prompt.withDefaults() to preserve the previous behaviour. - CompleteCompletion.total and .hasMore are now absent from the wire when not set, rather than being emitted as null. - ServerParameters no longer carries Jackson annotations; it is an internal configuration class, not a wire type. What now works that did not before - CompleteReference polymorphic dispatch (PromptReference vs ResourceReference) works through a plain readValue or convertValue call — no hand-rolled map inspection required. - LoggingLevel deserialization is lenient: unknown level strings produce null instead of throwing. - All domain records now tolerate unknown JSON fields, so a client built against an older SDK version will not fail when a newer server sends fields it does not yet recognise. - Null optional fields are consistently absent from serialized output regardless of ObjectMapper configuration. Documentation - CONTRIBUTING adds an "Evolving wire-serialized records" section: a 9-rule recipe and example for adding a field safely. - MIGRATION-2.0 documents all breaking changes listed above. Follow-up coming next Several spec-required fields (e.g. JSONRPCError.code/message, ProgressNotification.progress, CreateMessageRequest.maxTokens, CallToolResult.content) are stored as nullable Java types without a null guard. If constructed with null, the NON_ABSENT rule silently omits them, producing invalid wire JSON without throwing. Fix: compact canonical constructors with Assert.notNull, following the pattern already in JSONRPCRequest. Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

tzolov

Please return the @formatter:off for the enum types because combined with the json properties the values are not readable. I've marked few places perhaps there are more.

Additionally the JSONRPCMessage, JSONRPCResponse, JSONRPCError, JSONRPCNotification, JSONRPCRequest and the deserializeJsonRpcMessage are not really MCP Schema related but internal sdk implementation detail and can be moved in a separate class. I guess we can do it in another follow up PR.

tzolov · 2026-04-23T10:41:42Z

-			@JsonProperty("thisServer") THIS_SERVER,
-			@JsonProperty("allServers")ALL_SERVERS
-		} // @formatter:on
+			@JsonProperty("none")


the @Formatter:off was used on purpose. Without it the content is unreadable.

tzolov · 2026-04-23T10:41:52Z


 		public enum StopReason {

-		// @formatter:off


the @Formatter:off was used on purpose. Without it the content is unreadable.

tzolov · 2026-04-23T10:42:23Z


 		public enum Action {

-		// @formatter:off


tzolov · 2026-04-23T12:38:23Z

 						"SYSTEMDRIVE", "SYSTEMROOT", "TEMP", "USERNAME", "USERPROFILE")
 				: Arrays.asList("HOME", "LOGNAME", "PATH", "SHELL", "TERM", "USER");

-	@JsonProperty("command")


If not mistaken the ServerParameters are modeling the Claude Desktop MCP json configuration (or subset of it) : https://modelcontextprotocol.io/docs/develop/connect-local-servers
Therefore the annotations serve this purpose.

That's just a Claude thing, not specification thing. We don't use it to serialize/deserialize and we don't expect that kind of usage. These annotations should be removed.

tzolov · 2026-04-23T14:38:42Z

Rebased, edited, squashed and merged at 4c85963

chemicL · 2026-04-24T08:32:16Z

Please return the @formatter:off for the enum types because combined with the json properties the values are not readable. I've marked few places perhaps there are more.

I didn't catch that. In fact, there is an open issue to address this in the formatter: spring-io/spring-javaformat#393 - would be great to have that.

Additionally the JSONRPCMessage, JSONRPCResponse, JSONRPCError, JSONRPCNotification, JSONRPCRequest and the deserializeJsonRpcMessage are not really MCP Schema related but internal sdk implementation detail and can be moved in a separate class. I guess we can do it in another follow up PR.

That would make sense, I'll try to address it.

chemicL added 2 commits April 20, 2026 17:20

Update javadocs and years in headers

3e0cf9f

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

chemicL added breaking-change v2 labels Apr 20, 2026

chemicL added 3 commits April 20, 2026 18:47

Formatting

d7de6b8

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

Merge branch 'main' into json-compatibility

52edd37

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

Update migration doc

d1cad25

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

chemicL mentioned this pull request Apr 20, 2026

feat!: guard required MCP spec fields against null #928

Draft

9 tasks

Remove temporary file

12905a4

Signed-off-by: Dariusz Jędrzejczyk <2554306+chemicL@users.noreply.github.com>

tzolov reviewed Apr 23, 2026

View reviewed changes

tzolov added this to the 2.0.0-M1 milestone Apr 23, 2026

tzolov closed this Apr 23, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Consistent JSON forward/backward compatibility (2.0 foundation)#927

Consistent JSON forward/backward compatibility (2.0 foundation)#927
chemicL wants to merge 6 commits intomainfrom
json-compatibility

chemicL commented Apr 20, 2026

Uh oh!

tzolov left a comment

Uh oh!

tzolov Apr 23, 2026

Uh oh!

tzolov Apr 23, 2026

Uh oh!

tzolov Apr 23, 2026

Uh oh!

tzolov Apr 23, 2026

Uh oh!

chemicL Apr 24, 2026

Uh oh!

tzolov commented Apr 23, 2026

Uh oh!

chemicL commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

chemicL commented Apr 20, 2026

Motivation and Context

Breaking Changes

What now works that did not before

Documentation

Follow-up coming next

Types of changes

Checklist

Uh oh!

tzolov left a comment

Choose a reason for hiding this comment

Uh oh!

tzolov Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

tzolov Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

tzolov Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

tzolov Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

chemicL Apr 24, 2026

Choose a reason for hiding this comment

Uh oh!

tzolov commented Apr 23, 2026

Uh oh!

chemicL commented Apr 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants