René's URL Explorer Experiment

Title: feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization by chemicL · Pull Request #928 · modelcontextprotocol/java-sdk · GitHub

Open Graph Title: feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization by chemicL · Pull Request #928 · modelcontextprotocol/java-sdk

X Title: feat!: enforce required MCP spec fields in McpSchema; lenient wire deserialization by chemicL · Pull Request #928 · modelcontextprotocol/java-sdk

Description: Motivation and Context Every wire-serialized record in McpSchema now validates spec-required fields at construction time. Wire deserialization is intentionally lenient: a missing required field is replaced with a documented default and a WARN is logged, instead of failing the parse. A required-first builder convention is introduced across the schema so it is no longer possible to obtain a builder that is missing required state. Required-field guards Every wire record's compact constructor asserts non-null (and non-empty for String identifiers like name, uri, uriTemplate, version) on its spec-required components. Passing null now throws IllegalArgumentException at construction time instead of silently producing invalid JSON via @JsonInclude(NON_ABSENT). This applies to the JSON-RPC envelopes, lifecycle types, resource/prompt/tool requests and results, sampling and elicitation, content records, root, complete, logging and progress notifications, and the two CompleteReference implementations. See MIGRATION-2.0.md for the full list. Lenient wire deserialization For each of those records (except JSONRPCResponse.JSONRPCError, which still fails fast) a @JsonCreator static fromJson factory substitutes a documented default for any absent required field — "" for strings, [] for collections, {} for maps, 0 / 0.0 for numerics, INFO for LoggingLevel, USER for SamplingMessage.role, ASSISTANT for CreateMessageResult.role, CANCEL for ElicitResult.action, {values=[]} for CompleteResult.completion — and logs a WARN naming the field and the value used. Application code can still observe a malformed message and react, but the SDK no longer halts the conversation. Builder convention Records that have a builder gain a required-first factory method builder(req1, req2, …); setters for required fields are removed from the builder so it cannot be left in an invalid state. Existing no-arg builder() factories and required-field setters are kept where source compatibility demands it but are marked @deprecated. New builders are also added for several records that previously had none (ProgressNotification, JSONRPCError, CompleteRequest, list/result types, content records, ...). JSON-RPC envelope ergonomics Previously every JSON-RPC envelope had to be constructed via the canonical record constructor and the literal "2.0" string had to be threaded through every call site, e.g. new JSONRPCRequest("2.0", "tools/call", id, params) new JSONRPCResponse("2.0", id, result, null) new JSONRPCResponse("2.0", id, null, new JSONRPCError(code, message, null)) Now: new JSONRPCRequest("tools/call", id, params) // jsonrpc defaulted new JSONRPCNotification("notifications/initialized") // params optional JSONRPCResponse.result(id, result) // factory JSONRPCResponse.error(id, new JSONRPCError(code, message)) // 2-arg error JSONRPCResponse's compact constructor additionally enforces the JSON-RPC invariant that exactly one of result / error is set — previously the SDK could build envelopes that violated the protocol. CompleteReference changes PromptReference.equals/hashCode now key on name only (previously derived from identifier()+type()). Two refs with the same name but different titles now compare equal — code using PromptReference as a map/set key should be audited. PromptReference's compact constructor pins type to "ref/prompt" and logs a WARN if the caller supplies a different non-null value. The legacy two-arg PromptReference(String type, String name) constructor remains @deprecated. ResourceReference's record components are reduced from (type, uri) to (uri) — positional construction breaks. The legacy ResourceReference(String type, String uri) constructor stays @deprecated and ignores type. CompleteReference.identifier() is @deprecated and now returns null via a default method on the interface. Tests / refactor Conformance harness, integration tests, sample apps, and internal callers were migrated to the new builder factories and convenience constructors. No semantic changes to client/server runtime behaviour beyond the McpSchema changes above. Docs MIGRATION-2.0.md: required-field section now covers the broader record set and the lenient-deserialization behaviour; PromptReference WARN behaviour and ResourceReference component reduction are documented; the JSON-RPC envelope section is rewritten to compare the pre-2.0 surface with the new one. CONTRIBUTING.md: the "Evolving wire-serialized records" recipe is split into two cases — adding a new optional field (existing rules) and adding/maintaining a spec-required field (new rules covering Assert in compact constructor, @JsonCreator fromJson with defaults and WARN, required-first builder factory). How Has This Been Tested? Test code that constructed these records without required fields was updated to supply valid values; those tests were testing capability-check or error-path logic that fires after construction, so the missing fields were incidental rather than intentional. Breaking Changes PromptReference.equals/hashCode now key on name only (previously derived from identifier()+type()). Two refs with the same name but different titles now compare equal — code using PromptReference as a map/set key should be audited. PromptReference's compact constructor pins type to "ref/prompt" and logs a WARN if the caller supplies a different non-null value. The legacy two-arg PromptReference(String type, String name) constructor remains @deprecated. ResourceReference's record components are reduced from (type, uri) to (uri) — positional construction breaks. The legacy ResourceReference(String type, String uri) constructor stays @deprecated and ignores type. CompleteReference.identifier() is @deprecated and now returns null via a default method on the interface. 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

Open Graph Description: Motivation and Context Every wire-serialized record in McpSchema now validates spec-required fields at construction time. Wire deserialization is intentionally lenient: a missing required field is ...

X Description: Motivation and Context Every wire-serialized record in McpSchema now validates spec-required fields at construction time. Wire deserialization is intentionally lenient: a missing required field is ...

Opengraph URL: https://github.com/modelcontextprotocol/java-sdk/pull/928

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width