ruby-mcp-client 1.1.0 → 2.0.0

data/lib/mcp_client/oauth_client.rb

@@ -20,6 +20,8 @@ module MCPClient
     # @option options [String, nil] :name Optional name for this server
     # @option options [Logger, nil] :logger Optional logger
     # @option options [Object, nil] :storage Storage backend for OAuth tokens and client info
+    # @option options [String, nil] :client_id_metadata_url HTTPS URL of this client's
+    #   Client ID Metadata Document (SEP-991)
     # @return [ServerHTTP] OAuth-enabled HTTP server
     def self.create_http_server(server_url:, **options)
       opts = default_server_options.merge(options)
@@ -29,7 +31,8 @@ module MCPClient
         redirect_uri: opts[:redirect_uri],
         scope: opts[:scope],
         logger: opts[:logger],
-        storage: opts[:storage]
+        storage: opts[:storage],
+        client_id_metadata_url: opts[:client_id_metadata_url]
       )
 
       ServerHTTP.new(
@@ -57,7 +60,8 @@ module MCPClient
         redirect_uri: opts[:redirect_uri],
         scope: opts[:scope],
         logger: opts[:logger],
-        storage: opts[:storage]
+        storage: opts[:storage],
+        client_id_metadata_url: opts[:client_id_metadata_url]
       )
 
       ServerStreamableHTTP.new(
@@ -120,7 +124,8 @@ module MCPClient
         retry_backoff: 1,
         name: nil,
         logger: nil,
-        storage: nil
+        storage: nil,
+        client_id_metadata_url: nil
       }
     end
   end

data/lib/mcp_client/prompt.rb

@@ -5,23 +5,35 @@ module MCPClient
   class Prompt
     # @!attribute [r] name
     #   @return [String] the name of the prompt
+    # @!attribute [r] title
+    #   @return [String, nil] optional human-readable name of the prompt for display purposes
     # @!attribute [r] description
     #   @return [String] the description of the prompt
     # @!attribute [r] arguments
     #   @return [Hash] the JSON arguments for the prompt
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the prompt (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this prompt belongs to
-    attr_reader :name, :description, :arguments, :server
+    attr_reader :name, :title, :description, :arguments, :icons, :meta, :server
 
     # Initialize a new prompt
     # @param name [String] the name of the prompt
     # @param description [String] the description of the prompt
     # @param arguments [Hash] the JSON arguments for the prompt
+    # @param title [String, nil] optional human-readable name of the prompt for display purposes
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the prompt (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this prompt belongs to
-    def initialize(name:, description:, arguments: {}, server: nil)
+    def initialize(name:, description:, arguments: {}, title: nil, icons: nil, meta: nil, server: nil)
       @name = name
+      @title = title
       @description = description
       @arguments = arguments
+      @icons = icons
+      @meta = meta
       @server = server
     end
 
@@ -32,8 +44,11 @@ module MCPClient
     def self.from_json(data, server: nil)
       new(
         name: data['name'],
+        title: data['title'],
         description: data['description'],
         arguments: data['arguments'] || {},
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/resource.rb

@@ -17,9 +17,13 @@ module MCPClient
     #   @return [Integer, nil] optional size in bytes
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this resource belongs to
-    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :server
+    attr_reader :uri, :name, :title, :description, :mime_type, :size, :annotations, :icons, :meta, :server
 
     # Initialize a new resource
     # @param uri [String] unique identifier for the resource
@@ -29,8 +33,12 @@ module MCPClient
     # @param mime_type [String, nil] optional MIME type
     # @param size [Integer, nil] optional size in bytes
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this resource belongs to
-    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil, server: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri:, name:, title: nil, description: nil, mime_type: nil, size: nil, annotations: nil,
+                   icons: nil, meta: nil, server: nil)
       @uri = uri
       @name = name
       @title = title
@@ -38,8 +46,11 @@ module MCPClient
       @mime_type = mime_type
       @size = size
       @annotations = annotations
+      @icons = icons
+      @meta = meta
       @server = server
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Return the lastModified annotation value (ISO 8601 timestamp string)
     # @return [String, nil] the lastModified timestamp, or nil if not set
@@ -62,6 +73,8 @@ module MCPClient
         mime_type: data['mimeType'],
         size: data['size'],
         annotations: data['annotations'],
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/resource_content.rb

@@ -18,7 +18,9 @@ module MCPClient
     #   @return [String, nil] base64-encoded binary content (mutually exclusive with text)
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
-    attr_reader :uri, :name, :title, :mime_type, :text, :blob, :annotations
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource contents (MCP 2025-11-25)
+    attr_reader :uri, :name, :title, :mime_type, :text, :blob, :annotations, :meta
 
     # Initialize resource content
     # @param uri [String] unique identifier for the resource
@@ -28,7 +30,8 @@ module MCPClient
     # @param text [String, nil] text content (mutually exclusive with blob)
     # @param blob [String, nil] base64-encoded binary content (mutually exclusive with text)
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
-    def initialize(uri:, name:, title: nil, mime_type: nil, text: nil, blob: nil, annotations: nil)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource contents (MCP 2025-11-25)
+    def initialize(uri:, name:, title: nil, mime_type: nil, text: nil, blob: nil, annotations: nil, meta: nil)
       raise ArgumentError, 'ResourceContent cannot have both text and blob' if text && blob
       raise ArgumentError, 'ResourceContent must have either text or blob' if !text && !blob
 
@@ -39,6 +42,7 @@ module MCPClient
       @text = text
       @blob = blob
       @annotations = annotations
+      @meta = meta
     end
 
     # Create a ResourceContent instance from JSON data
@@ -52,7 +56,8 @@ module MCPClient
         mime_type: data['mimeType'],
         text: data['text'],
         blob: data['blob'],
-        annotations: data['annotations']
+        annotations: data['annotations'],
+        meta: data['_meta']
       )
     end
 

data/lib/mcp_client/resource_link.rb

@@ -19,7 +19,11 @@ module MCPClient
     #   @return [String, nil] optional display title for the resource
     # @!attribute [r] size
     #   @return [Integer, nil] optional size of the resource in bytes
-    attr_reader :uri, :name, :description, :mime_type, :annotations, :title, :size
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource link (MCP 2025-11-25)
+    attr_reader :uri, :name, :description, :mime_type, :annotations, :title, :size, :icons, :meta
 
     # Initialize a resource link
     # @param uri [String] URI of the linked resource
@@ -29,7 +33,11 @@ module MCPClient
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
     # @param title [String, nil] optional display title for the resource
     # @param size [Integer, nil] optional size of the resource in bytes
-    def initialize(uri:, name:, description: nil, mime_type: nil, annotations: nil, title: nil, size: nil)
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource link (MCP 2025-11-25)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri:, name:, description: nil, mime_type: nil, annotations: nil, title: nil, size: nil,
+                   icons: nil, meta: nil)
       @uri = uri
       @name = name
       @description = description
@@ -37,7 +45,10 @@ module MCPClient
       @annotations = annotations
       @title = title
       @size = size
+      @icons = icons
+      @meta = meta
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a ResourceLink instance from JSON data
     # @param data [Hash] JSON data from MCP server (content item with type 'resource_link')
@@ -50,7 +61,9 @@ module MCPClient
         mime_type: data['mimeType'],
         annotations: data['annotations'],
         title: data['title'],
-        size: data['size']
+        size: data['size'],
+        icons: data['icons'],
+        meta: data['_meta']
       )
     end
 

data/lib/mcp_client/resource_template.rb

@@ -16,9 +16,13 @@ module MCPClient
     #   @return [String, nil] optional MIME type for resources created from this template
     # @!attribute [r] annotations
     #   @return [Hash, nil] optional annotations that provide hints to clients
+    # @!attribute [r] icons
+    #   @return [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25, SEP-973)
+    # @!attribute [r] meta
+    #   @return [Hash, nil] optional `_meta` metadata attached to the resource template (MCP 2025-11-25)
     # @!attribute [r] server
     #   @return [MCPClient::ServerBase, nil] the server this resource template belongs to
-    attr_reader :uri_template, :name, :title, :description, :mime_type, :annotations, :server
+    attr_reader :uri_template, :name, :title, :description, :mime_type, :annotations, :icons, :meta, :server
 
     # Initialize a new resource template
     # @param uri_template [String] URI template following RFC 6570
@@ -27,16 +31,23 @@ module MCPClient
     # @param description [String, nil] optional description
     # @param mime_type [String, nil] optional MIME type
     # @param annotations [Hash, nil] optional annotations that provide hints to clients
+    # @param icons [Array<Hash>, nil] optional icons for display in user interfaces (MCP 2025-11-25)
+    # @param meta [Hash, nil] optional `_meta` metadata attached to the resource template (MCP 2025-11-25)
     # @param server [MCPClient::ServerBase, nil] the server this resource template belongs to
-    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil, annotations: nil, server: nil)
+    # rubocop:disable Metrics/ParameterLists
+    def initialize(uri_template:, name:, title: nil, description: nil, mime_type: nil, annotations: nil,
+                   icons: nil, meta: nil, server: nil)
       @uri_template = uri_template
       @name = name
       @title = title
       @description = description
       @mime_type = mime_type
       @annotations = annotations
+      @icons = icons
+      @meta = meta
       @server = server
     end
+    # rubocop:enable Metrics/ParameterLists
 
     # Create a ResourceTemplate instance from JSON data
     # @param data [Hash] JSON data from MCP server
@@ -50,6 +61,8 @@ module MCPClient
         description: data['description'],
         mime_type: data['mimeType'],
         annotations: data['annotations'],
+        icons: data['icons'],
+        meta: data['_meta'],
         server: server
       )
     end

data/lib/mcp_client/root.rb

@@ -1,26 +1,39 @@
 # frozen_string_literal: true
 
+require 'uri'
+
 module MCPClient
   # Represents an MCP Root - a URI that defines a boundary where servers can operate
   # Roots are declared by clients to inform servers about relevant resources and their locations
   class Root
-    attr_reader :uri, :name
+    attr_reader :uri, :name, :meta
 
     # Create a new Root
-    # @param uri [String] The URI for the root (typically file:// URI)
+    # @param uri [String] The URI for the root. Per the MCP specification this
+    #   MUST be a file:// URI ("This **MUST** be a `file://` URI in the current
+    #   specification" - client/roots.mdx, 2025-11-25)
     # @param name [String, nil] Optional human-readable name for display purposes
-    def initialize(uri:, name: nil)
+    # @param meta [Hash, nil] Optional _meta field attached to the root (schema.ts Root._meta)
+    # @raise [ArgumentError] if uri is not a valid file:// URI or contains '..' path segments
+    def initialize(uri:, name: nil, meta: nil)
+      validate_uri!(uri)
+      # Root._meta is an object of arbitrary keys per the schema
+      raise ArgumentError, "Root _meta must be a Hash, got #{meta.class}" if meta && !meta.is_a?(Hash)
+
       @uri = uri
       @name = name
+      @meta = meta
     end
 
     # Create a Root from a JSON hash
-    # @param json [Hash] The JSON hash with 'uri' and optional 'name' keys
+    # @param json [Hash] The JSON hash with 'uri' and optional 'name' and '_meta' keys
     # @return [Root]
+    # @raise [ArgumentError] if the uri is missing or not a valid file:// URI
     def self.from_json(json)
       new(
         uri: json['uri'] || json[:uri],
-        name: json['name'] || json[:name]
+        name: json['name'] || json[:name],
+        meta: json['_meta'] || json[:_meta]
       )
     end
 
@@ -29,6 +42,7 @@ module MCPClient
     def to_h
       result = { 'uri' => @uri }
       result['name'] = @name if @name
+      result['_meta'] = @meta if @meta
       result
     end
 
@@ -42,13 +56,13 @@ module MCPClient
     def ==(other)
       return false unless other.is_a?(Root)
 
-      uri == other.uri && name == other.name
+      uri == other.uri && name == other.name && meta == other.meta
     end
 
     alias eql? ==
 
     def hash
-      [uri, name].hash
+      [uri, name, meta].hash
     end
 
     # String representation
@@ -59,5 +73,45 @@ module MCPClient
     def inspect
       "#<MCPClient::Root uri=#{uri.inspect} name=#{name.inspect}>"
     end
+
+    private
+
+    # Validate that the uri is a well-formed file:// URI without path traversal.
+    # Spec (client/roots.mdx, 2025-11-25): the root uri "MUST be a `file://` URI
+    # in the current specification", and clients "MUST ... Validate all root
+    # URIs to prevent path traversal".
+    # @param uri [Object] the uri to validate
+    # @return [void]
+    # @raise [ArgumentError] if the uri is invalid
+    def validate_uri!(uri)
+      raise ArgumentError, 'Root uri must be a String, got nil' if uri.nil?
+      raise ArgumentError, "Root uri must be a String, got #{uri.class}" unless uri.is_a?(String)
+
+      # The schema requires the literal file:// form ("must start with
+      # file://"), not merely a file scheme — file:relative and file:/path
+      # forms are rejected.
+      unless uri.downcase.start_with?('file://')
+        raise ArgumentError,
+              "Root uri must be a file:// URI (MCP spec: 'This MUST be a file:// URI'), got: #{uri.inspect}"
+      end
+
+      parsed = parse_uri(uri)
+      # Decode before the traversal check so percent-encoded segments
+      # (%2e%2e) cannot smuggle a '..' past validation.
+      decoded_path = URI::DEFAULT_PARSER.unescape(parsed.path.to_s)
+      return unless decoded_path.split('/').include?('..')
+
+      raise ArgumentError, "Root uri must not contain '..' path traversal segments, got: #{uri.inspect}"
+    end
+
+    # Parse a URI string, converting parse errors to ArgumentError
+    # @param uri [String] the uri string to parse
+    # @return [URI::Generic]
+    # @raise [ArgumentError] if the uri cannot be parsed
+    def parse_uri(uri)
+      URI.parse(uri)
+    rescue URI::InvalidURIError => e
+      raise ArgumentError, "Root uri is not a valid URI: #{uri.inspect} (#{e.message})"
+    end
   end
 end

data/lib/mcp_client/schema_validator.rb

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+module MCPClient
+  # Self-contained JSON Schema validator used to check a tool call result's
+  # structuredContent against the tool's declared outputSchema (MCP 2025-11-25
+  # server/tools spec: "Clients SHOULD validate structured results against this
+  # schema"; the default schema dialect is JSON Schema 2020-12 per SEP-1613).
+  #
+  # Only the common JSON Schema keywords are supported:
+  # - type (single value or array of values), enum, const
+  # - properties, required (objects)
+  # - items, minItems, maxItems (arrays)
+  # - minLength, maxLength, pattern (strings)
+  # - minimum, maximum, exclusiveMinimum, exclusiveMaximum (numbers)
+  #
+  # The full JSON Schema 2020-12 vocabulary ($ref/$defs, allOf/anyOf/oneOf/not,
+  # conditional keywords, additionalProperties, format assertions, ...) is out
+  # of scope: unrecognized keywords are ignored rather than misapplied, so
+  # validation is best-effort — it may accept data a full validator would
+  # reject, but it does not reject data that conforms to the schema. So that
+  # this gap is never silent, {.unsupported_keywords} reports which unapplied
+  # validation keywords a schema uses; callers surface them as a warning.
+  module SchemaValidator
+    # JSON Schema 2020-12 keywords that affect validation but that this
+    # validator does not evaluate: applicator/reference keywords, assertion
+    # keywords (multipleOf, uniqueItems, contains bounds, property-count
+    # bounds, dependentRequired), and format (asserted by full validators in
+    # format-assertion mode). Their presence means validation is partial: data
+    # may pass here that a full validator would reject.
+    UNSUPPORTED_KEYWORDS = %w[
+      $ref $dynamicRef $defs allOf anyOf oneOf not if then else
+      additionalProperties patternProperties propertyNames dependentSchemas
+      prefixItems contains minContains maxContains uniqueItems
+      multipleOf format dependentRequired minProperties maxProperties
+      unevaluatedProperties unevaluatedItems
+    ].freeze
+
+    # Keywords whose value is a single subschema to walk.
+    SUBSCHEMA_KEYWORDS = %w[
+      items contains additionalProperties propertyNames not if then else
+      unevaluatedItems unevaluatedProperties
+    ].freeze
+
+    # Keywords whose value is a map of name => subschema.
+    SUBSCHEMA_MAP_KEYWORDS = %w[properties patternProperties $defs definitions dependentSchemas].freeze
+
+    # Keywords whose value is an array of subschemas.
+    SUBSCHEMA_ARRAY_KEYWORDS = %w[allOf anyOf oneOf prefixItems].freeze
+
+    # List the unsupported JSON Schema keywords a schema uses (anywhere: at the
+    # top level or nested in subschemas). Property names that merely look like
+    # keywords (e.g. a property called 'not') are not reported, and
+    # data-carrying keywords (enum/const/default/examples) are not scanned.
+    # @param schema [Object] the JSON schema (string or symbol keys)
+    # @return [Array<String>] unique unsupported keywords, in discovery order
+    def self.unsupported_keywords(schema)
+      found = []
+      collect_unsupported_keywords(schema, found)
+      found.uniq
+    end
+
+    # Recursively collect unsupported keywords from a schema.
+    # @param schema [Object] a (sub)schema; non-Hash values are ignored
+    # @param found [Array<String>] accumulator
+    # @return [void]
+    def self.collect_unsupported_keywords(schema, found)
+      return unless schema.is_a?(Hash)
+
+      schema = schema.transform_keys(&:to_s)
+      found.concat(schema.keys & UNSUPPORTED_KEYWORDS)
+      schema.each do |keyword, value|
+        if SUBSCHEMA_KEYWORDS.include?(keyword)
+          collect_unsupported_keywords(value, found)
+        elsif SUBSCHEMA_MAP_KEYWORDS.include?(keyword) && value.is_a?(Hash)
+          value.each_value { |subschema| collect_unsupported_keywords(subschema, found) }
+        elsif SUBSCHEMA_ARRAY_KEYWORDS.include?(keyword) && value.is_a?(Array)
+          value.each { |subschema| collect_unsupported_keywords(subschema, found) }
+        end
+      end
+    end
+
+    # Validate data against a JSON Schema subset.
+    # Schema and data hashes may use string or symbol keys.
+    # @param data [Object] the value to validate
+    # @param schema [Hash] the JSON schema
+    # @param path [String] JSON-pointer-style location used in error messages
+    # @return [Array<String>] human-readable validation errors (empty if valid)
+    def self.validate(data, schema, path: '#')
+      return [] unless schema.is_a?(Hash)
+
+      schema = schema.transform_keys(&:to_s)
+      errors = []
+      errors.concat(validate_type(data, schema['type'], path)) if schema.key?('type')
+      errors.concat(validate_enum(data, schema, path))
+      case data
+      when Hash then errors.concat(validate_object(data, schema, path))
+      when Array then errors.concat(validate_array(data, schema, path))
+      when String then errors.concat(validate_string(data, schema, path))
+      when Numeric then errors.concat(validate_number(data, schema, path))
+      end
+      errors
+    end
+
+    # Validate the JSON type of a value.
+    # @param data [Object] the value
+    # @param type [String, Symbol, Array<String, Symbol>] expected type(s)
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_type(data, type, path)
+      types = (type.is_a?(Array) ? type : [type]).map(&:to_s)
+      return [] if types.any? { |t| type_match?(t, data) }
+
+      ["#{path}: expected type #{types.join(' or ')}, got #{json_type(data)}"]
+    end
+
+    # Whether a value matches a JSON Schema type name.
+    # Unknown type names are not enforced (returns true).
+    # @param type [String] the JSON Schema type name
+    # @param data [Object] the value
+    # @return [Boolean]
+    def self.type_match?(type, data)
+      case type
+      when 'object' then data.is_a?(Hash)
+      when 'array' then data.is_a?(Array)
+      when 'string' then data.is_a?(String)
+      when 'boolean' then data.equal?(true) || data.equal?(false)
+      when 'null' then data.nil?
+      when 'number' then data.is_a?(Numeric)
+      when 'integer' then integer?(data)
+      else true
+      end
+    end
+
+    # Whether a value is a JSON Schema integer. Per JSON Schema 2020-12 a
+    # number with a zero fractional part (e.g. 2.0) is a valid integer.
+    # @param data [Object] the value
+    # @return [Boolean]
+    def self.integer?(data)
+      return true if data.is_a?(Integer)
+      return false unless data.is_a?(Numeric)
+
+      (data % 1).zero?
+    end
+
+    # The JSON type name of a Ruby value (for error messages).
+    # @param data [Object] the value
+    # @return [String]
+    def self.json_type(data)
+      case data
+      when nil then 'null'
+      when true, false then 'boolean'
+      when Integer then 'integer'
+      when Numeric then 'number'
+      when String then 'string'
+      when Array then 'array'
+      when Hash then 'object'
+      else data.class.name
+      end
+    end
+
+    # Validate enum/const membership.
+    # @param data [Object] the value
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_enum(data, schema, path)
+      errors = []
+      if schema['enum'].is_a?(Array) && !schema['enum'].include?(data)
+        errors << "#{path}: value #{data.inspect} is not in enum #{schema['enum'].inspect}"
+      end
+      if schema.key?('const') && schema['const'] != data
+        errors << "#{path}: value #{data.inspect} does not equal const #{schema['const'].inspect}"
+      end
+      errors
+    end
+
+    # Validate an object against required/properties.
+    # @param data [Hash] the object
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_object(data, schema, path)
+      errors = []
+      Array(schema['required']).each do |raw_name|
+        name = raw_name.to_s
+        errors << "#{path}: missing required property '#{name}'" unless data.key?(name) || data.key?(name.to_sym)
+      end
+      properties = schema['properties']
+      return errors unless properties.is_a?(Hash)
+
+      properties.each do |raw_name, prop_schema|
+        next unless prop_schema.is_a?(Hash)
+
+        name = raw_name.to_s
+        key = if data.key?(name)
+                name
+              elsif data.key?(name.to_sym)
+                name.to_sym
+              end
+        next if key.nil?
+
+        errors.concat(validate(data[key], prop_schema, path: "#{path}/#{name}"))
+      end
+      errors
+    end
+
+    # Validate an array against items/minItems/maxItems.
+    # @param data [Array] the array
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_array(data, schema, path)
+      errors = []
+      min_items = schema['minItems']
+      max_items = schema['maxItems']
+      if min_items.is_a?(Numeric) && data.length < min_items
+        errors << "#{path}: expected at least #{min_items} items, got #{data.length}"
+      end
+      if max_items.is_a?(Numeric) && data.length > max_items
+        errors << "#{path}: expected at most #{max_items} items, got #{data.length}"
+      end
+      items = schema['items']
+      if items.is_a?(Hash)
+        data.each_with_index { |item, idx| errors.concat(validate(item, items, path: "#{path}/#{idx}")) }
+      end
+      errors
+    end
+
+    # Validate a string against minLength/maxLength/pattern.
+    # @param data [String] the string
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_string(data, schema, path)
+      errors = []
+      min_length = schema['minLength']
+      max_length = schema['maxLength']
+      if min_length.is_a?(Numeric) && data.length < min_length
+        errors << "#{path}: string is shorter than minLength #{min_length}"
+      end
+      if max_length.is_a?(Numeric) && data.length > max_length
+        errors << "#{path}: string is longer than maxLength #{max_length}"
+      end
+      errors.concat(validate_pattern(data, schema['pattern'], path))
+      errors
+    end
+
+    # Validate a string against a regular-expression pattern.
+    # Invalid patterns are not enforced.
+    # @param data [String] the string
+    # @param pattern [Object] the pattern keyword value
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_pattern(data, pattern, path)
+      return [] unless pattern.is_a?(String)
+      return [] if data.match?(Regexp.new(pattern))
+
+      ["#{path}: string does not match pattern #{pattern.inspect}"]
+    rescue RegexpError
+      []
+    end
+
+    # Validate a number against inclusive/exclusive bounds.
+    # @param data [Numeric] the number
+    # @param schema [Hash] string-keyed schema
+    # @param path [String] location for error messages
+    # @return [Array<String>] validation errors
+    def self.validate_number(data, schema, path)
+      errors = []
+      minimum = schema['minimum']
+      maximum = schema['maximum']
+      exclusive_min = schema['exclusiveMinimum']
+      exclusive_max = schema['exclusiveMaximum']
+      errors << "#{path}: value #{data} is less than minimum #{minimum}" if minimum.is_a?(Numeric) && data < minimum
+      errors << "#{path}: value #{data} is greater than maximum #{maximum}" if maximum.is_a?(Numeric) && data > maximum
+      if exclusive_min.is_a?(Numeric) && data <= exclusive_min
+        errors << "#{path}: value #{data} must be greater than exclusiveMinimum #{exclusive_min}"
+      end
+      if exclusive_max.is_a?(Numeric) && data >= exclusive_max
+        errors << "#{path}: value #{data} must be less than exclusiveMaximum #{exclusive_max}"
+      end
+      errors
+    end
+  end
+end