From 1fc698bb8e6af313674c132eb9383458fdcbd907 Mon Sep 17 00:00:00 2001 From: Koichi ITO Date: Fri, 1 May 2026 02:17:31 +0900 Subject: [PATCH] Advertise JSON Schema 2020-12 dialect on emitted tool schemas ## Motivation and Context MCP 2025-11-25 (SEP-1613) establishes JSON Schema 2020-12 as the default dialect for MCP schema definitions. https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1613 The Ruby SDK was emitting tool input and output schemas with no `$schema` field, leaving the dialect implicit and inconsistent with the TypeScript SDK (`packages/core/src/util/standardSchema.ts`, which emits with `target: 'draft-2020-12'`) and the Python SDK (which preserves `$schema` in its types and conformance fixtures). `Tool::Schema#to_h` now includes `"$schema": "https://json-schema.org/draft/2020-12/schema"` unless the user supplied a different `$schema` value, so clients see the canonical dialect URI on the wire. Runtime metaschema and argument validation remain on draft-04 because the `json-schema` gem does not yet support 2020-12. Switching the runtime validator is left as a separate change because it requires either replacing the gem or waiting for upstream 2020-12 support. ## How Has This Been Tested? Updated `Tool::Schema#to_h` expectations across `input_schema_test`, `output_schema_test`, `tool_test`, and the `tools/list` server tests to reflect the new `$schema` field. Added focused regression tests: - `to_h` preserves a user-supplied `$schema` URI rather than overwriting it (covered for both symbol-keyed input and the string-keyed Hash form that goes through the initializer's `symbolize_names` normalization) - `validate_arguments` / `validate_result` continue to work when the user supplies a 2020-12 `$schema` URI on the schema (the validator strips the unknown top-level dialect URI before invoking the draft-04 validator, instead of raising `JSON::Schema::SchemaError`) - `tools/list` JSON-RPC response includes the 2020-12 `$schema` on both `inputSchema` and `outputSchema` (transport-boundary assertion) `bundle exec rake test` and `bundle exec rake rubocop` both pass. ## Breaking Changes Additive change. Tolerant consumers of the `tools/list` payload are unaffected. Consumers that strictly assert hash equality on the emitted `inputSchema` / `outputSchema` need to account for the new `$schema` key, but no schema semantics change. Schemas using 2020-12-only keywords (e.g. `prefixItems`, nested `$schema` on subschemas) are still rejected by the draft-04 metaschema validator, as before. Lifting that restriction depends on adopting a 2020-12-capable validator and is out of scope for this change. --- lib/mcp/tool/schema.rb | 26 ++++++++++-- test/mcp/server_test.rb | 22 +++++++++- test/mcp/tool/input_schema_test.rb | 60 ++++++++++++++++++++++++-- test/mcp/tool/output_schema_test.rb | 45 ++++++++++++++++++-- test/mcp/tool_test.rb | 65 ++++++++++++++++++++++++----- 5 files changed, 196 insertions(+), 22 deletions(-) diff --git a/lib/mcp/tool/schema.rb b/lib/mcp/tool/schema.rb index de6d4d7d..98a137ab 100644 --- a/lib/mcp/tool/schema.rb +++ b/lib/mcp/tool/schema.rb @@ -5,6 +5,12 @@ module MCP class Tool class Schema + # JSON Schema 2020-12 is the default dialect for MCP schema definitions + # per MCP 2025-11-25 (SEP-1613). Note: emission only — runtime validation + # is still performed against the JSON Schema draft-04 metaschema because + # the `json-schema` gem does not yet support 2020-12. + JSON_SCHEMA_2020_12_URI = "https://json-schema.org/draft/2020-12/schema" + attr_reader :schema def initialize(schema = {}) @@ -18,17 +24,18 @@ def ==(other) end def to_h - @schema + return @schema if @schema.key?(:"$schema") + + { "$schema": JSON_SCHEMA_2020_12_URI }.merge(@schema) end private def fully_validate(data) - JSON::Validator.fully_validate(to_h, data) + JSON::Validator.fully_validate(schema_for_validation, data) end def validate_schema! - schema = to_h gem_path = File.realpath(Gem.loaded_specs["json-schema"].full_gem_path) schema_reader = JSON::Schema::Reader.new( accept_uri: false, @@ -38,11 +45,22 @@ def validate_schema! # Converts metaschema to a file URI for cross-platform compatibility metaschema_uri = JSON::Util::URI.file_uri(metaschema_path.expand_path.cleanpath.to_s.tr("\\", "/")) metaschema = metaschema_uri.to_s - errors = JSON::Validator.fully_validate(metaschema, schema, schema_reader: schema_reader) + errors = JSON::Validator.fully_validate(metaschema, schema_for_validation, schema_reader: schema_reader) if errors.any? raise ArgumentError, "Invalid JSON Schema: #{errors.join(", ")}" end end + + # The `json-schema` gem's draft-04 validator cannot resolve newer or unknown `$schema` + # dialect URIs. Strip the top-level `$schema` before validation so a dialect URI + # (whether SDK-injected by `to_h` or user-supplied) does not break the validator. + def schema_for_validation + return @schema unless @schema.key?(:"$schema") + + copy = @schema.dup + copy.delete(:"$schema") + copy + end end end end diff --git a/test/mcp/server_test.rb b/test/mcp/server_test.rb index a8f3ea0d..1386ae2f 100644 --- a/test/mcp/server_test.rb +++ b/test/mcp/server_test.rb @@ -263,7 +263,9 @@ class ServerTest < ActiveSupport::TestCase assert_equal "test_tool", result[:tools][0][:name] assert_equal "Test tool", result[:tools][0][:title] assert_equal "A test tool", result[:tools][0][:description] - assert_equal({ type: "object" }, result[:tools][0][:inputSchema]) + assert_equal( + { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }, result[:tools][0][:inputSchema] + ) assert_equal({ foo: "bar" }, result[:tools][0][:_meta]) assert_instrumentation_data({ method: "tools/list" }) end @@ -284,6 +286,24 @@ class ServerTest < ActiveSupport::TestCase assert_equal({ foo: "bar" }, result[:tools][0][:_meta]) end + test "#handle tools/list emits 2020-12 $schema on inputSchema and outputSchema" do + tool_with_output = Tool.define( + name: "tool_with_output", + description: "tool with output schema", + input_schema: { properties: { msg: { type: "string" } } }, + output_schema: { properties: { result: { type: "string" } } }, + ) do + Tool::Response.new([{ type: "text", content: "OK" }]) + end + server = Server.new(name: "test_server", tools: [tool_with_output]) + + response = server.handle({ jsonrpc: "2.0", method: "tools/list", id: 1 }) + tool = response[:result][:tools][0] + + assert_equal "https://json-schema.org/draft/2020-12/schema", tool[:inputSchema][:"$schema"] + assert_equal "https://json-schema.org/draft/2020-12/schema", tool[:outputSchema][:"$schema"] + end + test "#handle tools/call executes tool and returns result" do tool_name = "test_tool" tool_args = { arg: "value" } diff --git a/test/mcp/tool/input_schema_test.rb b/test/mcp/tool/input_schema_test.rb index 03bce287..80a57828 100644 --- a/test/mcp/tool/input_schema_test.rb +++ b/test/mcp/tool/input_schema_test.rb @@ -13,7 +13,12 @@ class InputSchemaTest < ActiveSupport::TestCase test "to_h returns a hash representation of the input schema" do input_schema = InputSchema.new(properties: { message: { type: "string" } }, required: ["message"]) assert_equal( - { type: "object", properties: { message: { type: "string" } }, required: ["message"] }, + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { message: { type: "string" } }, + required: ["message"], + }, input_schema.to_h, ) end @@ -21,11 +26,52 @@ class InputSchemaTest < ActiveSupport::TestCase test "to_h returns a hash representation of the input schema with additionalProperties set to false" do input_schema = InputSchema.new(properties: { message: { type: "string" } }, required: ["message"], additionalProperties: false) assert_equal( - { type: "object", properties: { message: { type: "string" } }, required: ["message"], additionalProperties: false }, + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { message: { type: "string" } }, + required: ["message"], + additionalProperties: false, + }, input_schema.to_h, ) end + test "to_h preserves user-supplied $schema dialect" do + input_schema = InputSchema.new( + "$schema": "https://json-schema.org/draft/2019-09/schema", + properties: { message: { type: "string" } }, + ) + assert_equal "https://json-schema.org/draft/2019-09/schema", input_schema.to_h[:"$schema"] + end + + test "validate_arguments works when user supplies a 2020-12 $schema" do + input_schema = InputSchema.new( + "$schema": "https://json-schema.org/draft/2020-12/schema", + properties: { foo: { type: "string" } }, + required: ["foo"], + ) + assert_nil(input_schema.validate_arguments(foo: "bar")) + assert_raises(InputSchema::ValidationError) do + input_schema.validate_arguments({ foo: 123 }) + end + end + + test "to_h preserves user-supplied $schema given via string key" do + # The initializer normalizes input through `JSON.parse(..., + # symbolize_names: true)`, so a string-keyed `"$schema"` should + # arrive at `schema_for_validation` the same as a symbol-keyed one. + input_schema = InputSchema.new( + { + "$schema" => "https://json-schema.org/draft/2020-12/schema", + "properties" => { "foo" => { "type" => "string" } }, + "required" => ["foo"], + }, + ) + assert_equal "https://json-schema.org/draft/2020-12/schema", input_schema.to_h[:"$schema"] + assert_nil(input_schema.validate_arguments(foo: "bar")) + end + test "missing_required_arguments returns an array of missing required arguments" do input_schema = InputSchema.new(properties: { message: { type: "string" } }, required: ["message"]) assert_equal ["message"], input_schema.missing_required_arguments({}) @@ -38,7 +84,15 @@ class InputSchemaTest < ActiveSupport::TestCase test "valid schema initialization" do schema = InputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"]) - assert_equal({ type: "object", properties: { foo: { type: "string" } }, required: ["foo"] }, schema.to_h) + assert_equal( + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { foo: { type: "string" } }, + required: ["foo"], + }, + schema.to_h, + ) end test "invalid schema raises argument error" do diff --git a/test/mcp/tool/output_schema_test.rb b/test/mcp/tool/output_schema_test.rb index 5445462d..073de2c6 100644 --- a/test/mcp/tool/output_schema_test.rb +++ b/test/mcp/tool/output_schema_test.rb @@ -8,11 +8,38 @@ class OutputSchemaTest < ActiveSupport::TestCase test "to_h returns a hash representation of the output schema" do output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"]) assert_equal( - { type: "object", properties: { result: { type: "string" } }, required: ["result"] }, + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" } }, + required: ["result"], + }, output_schema.to_h, ) end + test "to_h preserves user-supplied $schema dialect" do + output_schema = OutputSchema.new( + "$schema": "https://json-schema.org/draft/2019-09/schema", + properties: { result: { type: "string" } }, + ) + assert_equal "https://json-schema.org/draft/2019-09/schema", output_schema.to_h[:"$schema"] + end + + test "validate_result works when user supplies a 2020-12 $schema" do + output_schema = OutputSchema.new( + "$schema": "https://json-schema.org/draft/2020-12/schema", + properties: { result: { type: "string" } }, + required: ["result"], + ) + assert_nothing_raised do + output_schema.validate_result({ result: "success" }) + end + assert_raises(OutputSchema::ValidationError) do + output_schema.validate_result({ result: 123 }) + end + end + test "validate_result validates result against the schema" do output_schema = OutputSchema.new(properties: { result: { type: "string" } }, required: ["result"]) assert_nothing_raised do @@ -57,7 +84,15 @@ class OutputSchemaTest < ActiveSupport::TestCase test "valid schema initialization" do schema = OutputSchema.new(properties: { foo: { type: "string" } }, required: ["foo"]) - assert_equal({ type: "object", properties: { foo: { type: "string" } }, required: ["foo"] }, schema.to_h) + assert_equal( + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { foo: { type: "string" } }, + required: ["foo"], + }, + schema.to_h, + ) end test "invalid schema raises argument error" do @@ -136,7 +171,10 @@ class OutputSchemaTest < ActiveSupport::TestCase test "empty schema is valid" do schema = OutputSchema.new - assert_equal({ type: "object" }, schema.to_h) + assert_equal( + { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }, + schema.to_h, + ) end test "validates complex nested schemas" do @@ -187,6 +225,7 @@ class OutputSchemaTest < ActiveSupport::TestCase }) assert_equal( { + "$schema": "https://json-schema.org/draft/2020-12/schema", type: "array", items: { properties: { foo: { type: "string" } }, diff --git a/test/mcp/tool_test.rb b/test/mcp/tool_test.rb index a0175ad4..e32df0a9 100644 --- a/test/mcp/tool_test.rb +++ b/test/mcp/tool_test.rb @@ -33,7 +33,7 @@ def call(message:, server_context: nil) title: "Mock Tool", description: "a mock tool for testing", icons: [{ mimeType: "image/png", sizes: ["48x48", "96x96"], src: "https://example.com", theme: "light" }], - inputSchema: { type: "object" }, + inputSchema: { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }, } tool = Tool.define( name: "mock_tool", @@ -109,7 +109,15 @@ class MockTool < Tool tool = MockTool assert_equal "my_mock_tool", tool.name_value assert_equal "a mock tool for testing", tool.description - assert_equal({ type: "object", properties: { message: { type: "string" } }, required: ["message"] }, tool.input_schema.to_h) + assert_equal( + { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { message: { type: "string" } }, + required: ["message"], + }, + tool.input_schema.to_h, + ) end test "defaults to class name as tool name" do @@ -126,7 +134,7 @@ class NoInputSchemaTool < Tool; end tool = NoInputSchemaTool - expected = { type: "object" } + expected = { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" } assert_equal expected, tool.input_schema.to_h end @@ -137,7 +145,12 @@ class InputSchemaTool < Tool tool = InputSchemaTool - expected = { type: "object", properties: { message: { type: "string" } }, required: ["message"] } + expected = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { message: { type: "string" } }, + required: ["message"], + } assert_equal expected, tool.input_schema.to_h end @@ -342,8 +355,13 @@ def call(message, server_context: nil) title: "Mock Tool", description: "a mock tool for testing", icons: [{ mimeType: "image/png", sizes: ["48x48", "96x96"], src: "https://example.com", theme: "light" }], - inputSchema: { type: "object" }, - outputSchema: { type: "object", properties: { result: { type: "string" } }, required: ["result"] }, + inputSchema: { "$schema": "https://json-schema.org/draft/2020-12/schema", type: "object" }, + outputSchema: { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" } }, + required: ["result"], + }, } tool = Tool.define( name: "mock_tool", @@ -376,7 +394,12 @@ class HashOutputSchemaTool < Tool end tool = HashOutputSchemaTool - expected = { type: "object", properties: { result: { type: "string" } }, required: ["result"] } + expected = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" } }, + required: ["result"], + } assert_equal expected, tool.output_schema.to_h end @@ -386,7 +409,12 @@ class OutputSchemaObjectTool < Tool end tool = OutputSchemaObjectTool - expected = { type: "object", properties: { result: { type: "string" } }, required: ["result"] } + expected = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" } }, + required: ["result"], + } assert_equal expected, tool.output_schema.to_h end @@ -436,7 +464,12 @@ class OutputSchemaObjectTool < Tool assert_equal "mock_tool", tool.name_value assert_equal "a mock tool for testing", tool.description assert_instance_of Tool::OutputSchema, tool.output_schema - expected_output_schema = { type: "object", properties: { result: { type: "string" } }, required: ["result"] } + expected_output_schema = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" } }, + required: ["result"], + } assert_equal expected_output_schema, tool.output_schema.to_h end @@ -458,10 +491,20 @@ def call(message:, server_context: nil) assert_equal "test_tool_with_output", tool.name_value assert_equal "a test tool with output schema", tool.description - expected_input = { type: "object", properties: { message: { type: "string" } }, required: ["message"] } + expected_input = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { message: { type: "string" } }, + required: ["message"], + } assert_equal expected_input, tool.input_schema.to_h - expected_output = { type: "object", properties: { result: { type: "string" }, success: { type: "boolean" } }, required: ["result", "success"] } + expected_output = { + "$schema": "https://json-schema.org/draft/2020-12/schema", + type: "object", + properties: { result: { type: "string" }, success: { type: "boolean" } }, + required: ["result", "success"], + } assert_equal expected_output, tool.output_schema.to_h end