skooma 0.3.8 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1425cf06717c3675b02d873d78da9f50b8b652748c33a86e838be37fcb164e7b
-  data.tar.gz: 761abc98b0394bf38330010c18a8536e21cc700308e834572406d2ee2e3a02ff
+  metadata.gz: 908f9232ad0bab42d205ee2aee29af1dc362f33a8a2a094d831098423e2a1099
+  data.tar.gz: f7f001ef01777d970c2ed4997baf387b478d857913f25bbabca1d9d733a51ca3
 SHA512:
-  metadata.gz: ffdf92bbb6d9feb0945cda5e8ff854bb883f03a3404f9ffdc753683ccebaa283f0d8c79e020fb41474b6b6ba01c1e10f4255a64b0bb635e9c16135c33b0dfdf0
-  data.tar.gz: 7c2aef17f070a2aeeb29d7b6cf3799b885f2eb0922fa27ffe671ae2aa7607df8a0f10426b95c0bd01b05e26a941a969e186568690de745340a8c121275d1bc3f
+  metadata.gz: 3745de933867d3b250d0ec085313162eda5bb9e57f2db4140a2c445b44de8c180c168f4177af6fc0ac82813c0328adafa145a584ab52b648be8ba3b46c522393
+  data.tar.gz: 3dadbfdfeb878cbb9cbf24b07ab613ccfbaeea803381de996103968d39f02aafaebae27552b0a916abb5eef4c9b7c8f9690df07a87f238756040b9aa94c5b25b

data/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning].
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-06-10
+
+### Added
+
+- Parse `multipart/form-data` and `application/x-www-form-urlencoded` request bodies before validation. File parts are read as binary strings, so uploads validate against `type: string` / `format: binary` schemas. Fixes file upload validation failing with errors like "body id required". ([@skryukov])
+- Respect the Media Type Object's `encoding` field for form bodies: fields with a JSON `contentType` are decoded before validation (multipart object-typed properties default to JSON per the spec). ([@skryukov])
+- Allow passing a custom coverage store to the RSpec/Minitest helpers via `coverage_store:` — any object implementing `load_data`, `save_data`, and `clear`. Useful for writing one coverage file per parallel CI runner and merging afterwards. ([@skryukov])
+- Support object-valued path parameters (`simple`, `label`, and `matrix` styles, explode-aware) and `form`-style object query parameters. Exploded form objects (`?x=1&y=2`) are gathered by matching the schema's `properties` names; non-exploded forms flatten under the parameter's name (`?point=x,1,y,2`). Properties are coerced to their declared types. ([@skryukov])
+- Support for external `$ref`s in OpenAPI documents. References like `$ref: './responses.yaml#/UsersResponse'` now resolve against the spec file's directory (or any source registered on the registry) and are wrapped with the appropriate OpenAPI object type — Response, Parameter, Header, RequestBody, PathItem, or a plain JSON Schema for `schema:` refs. Chained and self-recursive external refs are supported. ([@skryukov])
+- Support array-valued query parameters: respect the `style` and `explode` keywords (`form`, `spaceDelimited`, and `pipeDelimited` styles), coerce array items to the declared `items` type, and map the non-standard bracket convention (`ids[]=1&ids[]=2`) to array params. ([@dslh])
+- Support object-valued query parameters declared with the `deepObject` style (`filter[id]=1&filter[name]=foo`), coercing each property to its declared type. Parameter coercion now descends into array items (positional `prefixItems` first, then `items`) and object properties (`properties` first, then `additionalProperties`), while request/response bodies keep their JSON-native types. ([@skryukov])
+- Support array-valued header (`simple` style) and cookie (`form` style) parameters, splitting the delimited value and coercing each item to the declared `items` type. ([@skryukov])
+- Support cookie parameters, which were previously ignored entirely. ([@skryukov])
+- Support array-valued path parameters across the `simple`, `label`, and `matrix` styles (with `explode`), coercing each item to the declared `items` type. ([@skryukov])
+- Parse `content`-typed parameters (e.g. `content: {application/json: …}`) using the parameter's own media type before validation, instead of validating the raw string against a media type taken from the response. **Behavior change:** such values are now decoded per their media type (e.g. JSON), so a value that previously passed as a raw string may need to be sent in its serialized form (e.g. `"100"` rather than `100` for a JSON string). ([@skryukov])
+
+### Changed
+
+- Bumped minimum `json_skooma` to `~> 0.2.7` for the new typed `UnexpectedSchemaClassError` and public `Registry#load_json` (0.2.6 was yanked due to a packaging issue). ([@skryukov])
+
 ## [0.3.8] - 2026-04-16
 
 ### Fixed
@@ -183,6 +203,7 @@ and this project adheres to [Semantic Versioning].
 [@aburgel]: https://github.com/aburgel
 [@alexkalderimis]: https://github.com/alexkalderimis
 [@barnaclebarnes]: https://github.com/barnaclebarnes
+[@dslh]: https://github.com/dslh
 [@Envek]: https://github.com/Envek
 [@goodtouch]: https://github.com/goodtouch
 [@jandouwebeekman]: https://github.com/jandouwebeekman
@@ -192,7 +213,8 @@ and this project adheres to [Semantic Versioning].
 [@ursm]: https://github.com/ursm
 [@visini]: https://github.com/visini
 
-[Unreleased]: https://github.com/skryukov/skooma/compare/v0.3.8...HEAD
+[Unreleased]: https://github.com/skryukov/skooma/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/skryukov/skooma/compare/v0.3.8...v0.4.0
 [0.3.8]: https://github.com/skryukov/skooma/compare/v0.3.7...v0.3.8
 [0.3.7]: https://github.com/skryukov/skooma/compare/v0.3.6...v0.3.7
 [0.3.6]: https://github.com/skryukov/skooma/compare/v0.3.5...v0.3.6

data/README.md

@@ -55,6 +55,14 @@ RSpec.configure do |config|
   # To enable coverage, pass `coverage: :report` option,
   # and to raise an error when an operation is not covered, pass `coverage: :strict` option:
   config.include Skooma::RSpec[path_to_openapi, coverage: :report], type: :request
+
+  # To control where coverage data is stored (e.g. one file per parallel CI runner),
+  # pass a custom store via `coverage_store:` — any object implementing
+  # `load_data`, `save_data(defined, covered)`, and `clear` works.
+  # Treat the path entries as opaque values: their shape may gain dimensions
+  # (e.g. content type) in future versions.
+  store = Skooma::CoverageStore.new(file_path: "tmp/skooma_coverage_#{ENV["TEST_ENV_NUMBER"]}.json")
+  config.include Skooma::RSpec[path_to_openapi, coverage: :report, coverage_store: store], type: :request
 end
 ```
 
@@ -129,6 +137,10 @@ ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, path_p
 # and to raise an error when an operation is not covered, pass `coverage: :strict` option:
 ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, coverage: :report], type: :request
 
+# To control where coverage data is stored, pass a custom store via `coverage_store:`:
+store = Skooma::CoverageStore.new(file_path: "tmp/skooma_coverage_#{ENV["TEST_ENV_NUMBER"]}.json")
+ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, coverage: :report, coverage_store: store], type: :request
+
 # EXPERIMENTAL
 # To enable support for readOnly and writeOnly keywords, pass `enforce_access_modes: true` option:
 ActionDispatch::IntegrationTest.include Skooma::Minitest[path_to_openapi, enforce_access_modes: true], type: :request
@@ -176,6 +188,165 @@ class ItemsTest < ActionDispatch::IntegrationTest
 end
 ```
 
+### Splitting specs across files
+
+Skooma resolves external `$ref`s relative to the OpenAPI document's directory, so you can split a large spec into multiple files:
+
+```yaml
+# docs/openapi.yaml
+paths:
+  /users:
+    get:
+      responses:
+        '200':
+          $ref: './responses.yaml#/UsersResponse'
+  /health:
+    $ref: './paths.yaml#/Health'
+```
+
+References are wrapped with the appropriate OpenAPI object type based on context — `$ref` inside `responses` loads as a Response, inside `parameters` as a Parameter, inside `schema` as a JSON Schema, and so on. Chained (A → B → C) and self-recursive schemas work out of the box.
+
+Only local files are resolved by default. To load refs from other sources (e.g. HTTP), register a source on the registry:
+
+```ruby
+schema = Skooma::Minitest[path_to_openapi].schema
+schema.registry.add_source(
+  "https://example.com/schemas/",
+  JSONSkooma::Sources::Remote.new("https://example.com/schemas/")
+)
+```
+
+### Array query parameters
+
+Skooma deserializes array-valued query parameters according to their `style` and `explode`
+keywords (`form`, `spaceDelimited`, and `pipeDelimited` styles are supported),
+and coerces each item to the type declared in the `items` schema:
+
+```yaml
+- in: query
+  name: ids
+  schema:
+    type: array
+    items:
+      type: integer
+```
+
+```
+GET /things?ids=1&ids=2&ids=3 # ids => [1, 2, 3]
+```
+
+As a convenience, the non-standard Rails/Rack bracket convention is also recognized:
+`GET /things?ids[]=1&ids[]=2` matches the array parameter named `ids`.
+The bracket form is only used when the parameter declares `type: array` and
+the query string contains no exact `ids` key.
+
+### Object query parameters
+
+Skooma deserializes object-valued query parameters declared with the `deepObject`
+style, gathering the bracketed members and coercing each property to the type
+declared in its `properties` schema:
+
+```yaml
+- in: query
+  name: filter
+  style: deepObject
+  explode: true
+  schema:
+    type: object
+    properties:
+      id:
+        type: integer
+      name:
+        type: string
+```
+
+```
+GET /things?filter[id]=1&filter[name]=foo # filter => { "id" => 1, "name" => "foo" }
+```
+
+The default `form` style is also supported. Exploded form objects (the default)
+drop the parameter name — each property declared in the schema becomes its own
+query key — while non-exploded objects flatten under the parameter's name:
+
+```
+GET /things?x=1&y=2        # form, explode:  point => { "x" => 1, "y" => 2 }
+GET /things?point=x,1,y,2  # form:           point => { "x" => 1, "y" => 2 }
+```
+
+Note that exploded form objects are gathered by matching the schema's
+`properties` names, so members allowed only via `additionalProperties` are not
+recognized.
+
+### Header and cookie parameters
+
+Array-valued header (`simple` style) and cookie (`form` style) parameters are
+deserialized from their delimited form and each item is coerced to the declared
+`items` type:
+
+```
+X-Ids: 1,2,3            # X-Ids  => [1, 2, 3]
+Cookie: ids=1,2,3       # ids    => [1, 2, 3]
+```
+
+### Path parameters
+
+Array-valued path parameters are deserialized according to their `style`
+(`simple`, `label`, `matrix`) and `explode` keywords, with each item coerced to
+the declared `items` type:
+
+```
+GET /things/1,2,3          # simple:            id => [1, 2, 3]
+GET /things/.1.2.3         # label, explode:    id => [1, 2, 3]
+GET /things/;id=1;id=2     # matrix, explode:   id => [1, 2]
+```
+
+Object-valued path parameters flatten their properties into the segment and are
+rebuilt with each property coerced via the `properties` schema:
+
+```
+GET /points/x,1,y,2        # simple:            point => { "x" => 1, "y" => 2 }
+GET /points/x=1,y=2        # simple, explode:   point => { "x" => 1, "y" => 2 }
+GET /points/;x=1;y=2       # matrix, explode:   point => { "x" => 1, "y" => 2 }
+```
+
+### Form and multipart request bodies
+
+`application/x-www-form-urlencoded` and `multipart/form-data` request bodies
+are parsed before validation, so file uploads validate against their OpenAPI
+schemas. File parts are read as binary strings, matching
+`type: string` / `format: binary` properties:
+
+```yaml
+requestBody:
+  content:
+    multipart/form-data:
+      schema:
+        type: object
+        properties:
+          id: {type: string}
+          file: {type: string, format: binary}
+```
+
+The Media Type Object's `encoding` field is respected: a multipart or
+urlencoded field whose `contentType` is a JSON media type is decoded before
+validation, so its schema validates the structured value. For multipart
+bodies, object-typed properties default to JSON decoding per the spec:
+
+```yaml
+content:
+  multipart/form-data:
+    schema:
+      type: object
+      properties:
+        meta: {type: object}          # decoded as JSON (spec default)
+        file: {type: string, format: binary}
+    encoding:
+      meta: {contentType: application/json}
+```
+
+Custom parsers for other media types can be registered via
+`Skooma::BodyParsers.register("application/xml", ->(body, headers:) { ... })`.
+
 ## Alternatives
 
 - [openapi_first](https://github.com/ahx/openapi_first)
@@ -183,9 +354,7 @@ end
 
 ## Feature plans
 
-- Full support for external `$ref`s
 - Full OpenAPI 3.1.0 support:
-  - respect `style` and `explode` keywords
   - xml
 - Callbacks and webhooks validations
 - Example validations

data/lib/skooma/body_parsers.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "rack/utils"
+require "rack/multipart"
+
 module Skooma
   module BodyParsers
     class << self
@@ -49,5 +52,58 @@ module Skooma
       end
     end
     register "application/json", JSONParser
+
+    module FormURLEncodedParser
+      def self.call(body, **_options)
+        Rack::Utils.parse_nested_query(body)
+      # The set of parse error classes differs across Rack 2/3; a malformed
+      # body falls back to the raw string so schema validation rejects it.
+      rescue
+        body
+      end
+    end
+    register "application/x-www-form-urlencoded", FormURLEncodedParser
+
+    # Parses multipart bodies with Rack's multipart parser (the boundary is
+    # taken from the request's own Content-Type header). File parts are
+    # replaced by their content read as a binary string, so they validate
+    # against `type: string` / `format: binary` schemas.
+    module MultipartParser
+      def self.call(body, headers: nil, **_options)
+        content_type = headers && headers["Content-Type"]&.value
+        return body if content_type.nil? || body.nil?
+
+        input = StringIO.new(body.to_s.dup.force_encoding(Encoding::BINARY))
+        params = Rack::Multipart.parse_multipart(
+          "CONTENT_TYPE" => content_type,
+          "CONTENT_LENGTH" => input.size.to_s,
+          "rack.input" => input
+        )
+        return body if params.nil?
+
+        simplify(params)
+      # Rack 2/3 raise different errors on malformed multipart (Multipart::Error,
+      # EOFError, ...); fall back to the raw string so validation rejects it.
+      rescue
+        body
+      end
+
+      def self.simplify(value)
+        case value
+        when Hash
+          if value.key?(:tempfile)
+            value[:tempfile].read.force_encoding(Encoding::BINARY)
+          else
+            value.transform_values { |member| simplify(member) }
+          end
+        when Array
+          value.map { |member| simplify(member) }
+        else
+          value
+        end
+      end
+      private_class_method :simplify
+    end
+    register "multipart/form-data", MultipartParser
   end
 end

data/lib/skooma/external_refs.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Skooma
+  # External $ref resolution: upstream treats a referenced document as a single
+  # JSONSchema and errors out when the fragment points at a non-schema node
+  # inside a raw map (e.g. `responses.yaml#/Users`). Here we load the raw
+  # document, navigate to the fragment, and wrap the subtree as the referrer's
+  # own class so OpenAPI semantics are preserved.
+  module ExternalRefs
+    def resolve_ref(uri)
+      super
+    rescue JSONSkooma::UnexpectedSchemaClassError
+      load_external_ref(resolve_uri(uri))
+    end
+
+    private
+
+    def load_external_ref(resolved_uri)
+      base_uri = resolved_uri.dup.tap { |u| u.fragment = nil }
+      raw_doc = registry.load_json(base_uri)
+
+      data =
+        if resolved_uri.fragment.nil? || resolved_uri.fragment.empty?
+          raw_doc
+        else
+          JSONSkooma::JSONPointer.new(resolved_uri.fragment).eval(raw_doc)
+        end
+
+      raise JSONSkooma::RegistryError, "Could not resolve $ref #{resolved_uri}" if data.nil?
+
+      wrap_external_data(data, resolved_uri)
+    end
+
+    def wrap_external_data(data, uri)
+      wrapped = self.class.new(
+        data,
+        parent: root,
+        registry: registry,
+        cache_id: cache_id,
+        uri: uri,
+        metaschema_uri: metaschema_uri
+      )
+      wrapped.resolve_references
+      wrapped
+    end
+  end
+end

data/lib/skooma/instance.rb

@@ -7,6 +7,10 @@ module Skooma
         value = self&.value
         return self if value.nil?
 
+        Coercible.coerce_value(value, json)
+      end
+
+      def self.coerce_value(value, json)
         case json["type"]
         when "integer"
           begin
@@ -28,12 +32,77 @@ module Skooma
           value
           # convert_object(value, schema)
         when "array"
-          # convert_array(value, schema)
-          value
+          coerce_array_items(value, json["items"])
         else
           value
         end
       end
+
+      def self.coerce_array_items(value, items_schema)
+        return value unless value.is_a?(Array)
+        return value unless schema_object?(items_schema)
+
+        value.map { |item| item.is_a?(String) ? coerce_value(item, items_schema) : item }
+      end
+
+      # Recursive coercion for *parameters* only. Parameter values arrive as
+      # all-strings, so we descend into array items (positional `prefixItems`
+      # first, then `items`) and object properties (`properties` first, then
+      # `additionalProperties`), coercing each to its declared type.
+      # Request/response *bodies* are only shallowly coerced (top level, via
+      # `coerce` above), so a *nested* JSON body value like `{"count": "5"}`
+      # against `integer` stays invalid.
+      def deep_coerce(json)
+        return if value.nil?
+
+        Coercible.deep_coerce_value(value, json)
+      end
+
+      def self.deep_coerce_value(value, json)
+        return value if value.nil?
+
+        case json["type"]
+        when "array"
+          return value unless value.is_a?(Array)
+
+          prefix_items = json["prefixItems"]
+          items = json["items"]
+
+          value.map.with_index do |item, index|
+            schema = prefix_schema(prefix_items, index) || items
+            schema_object?(schema) ? deep_coerce_value(item, schema) : item
+          end
+        when "object"
+          return value unless value.is_a?(Hash)
+
+          properties = json["properties"]
+          additional_properties = json["additionalProperties"]
+
+          value.each_with_object({}) do |(key, item), coerced|
+            schema = properties.respond_to?(:key?) ? properties[key] : nil
+            schema ||= additional_properties
+            coerced[key] = schema_object?(schema) ? deep_coerce_value(item, schema) : item
+          end
+        else
+          # Scalar schema: only scalar values are coercible. A structural value
+          # here means a type mismatch (e.g. `deepObject` against a scalar
+          # schema) — leave it for validation to reject rather than coerce.
+          (value.is_a?(Hash) || value.is_a?(Array)) ? value : coerce_value(value, json)
+        end
+      end
+
+      # True when `node` is a real subschema (a JSON object), excluding boolean
+      # schemas like `items: true`.
+      def self.schema_object?(node)
+        node.is_a?(JSONSkooma::JSONSchema) && node.type == "object"
+      end
+
+      # The positional subschema for `index` when `prefixItems` is present.
+      def self.prefix_schema(prefix_items, index)
+        return unless prefix_items.is_a?(JSONSkooma::JSONNode) && prefix_items.type == "array"
+
+        prefix_items[index]
+      end
     end
 
     class Attribute < JSONSkooma::JSONNode

data/lib/skooma/keywords/oas_3_1/dialect/additional_properties.rb

@@ -22,7 +22,7 @@ module Skooma
               properties_result = result.sibling(instance, "properties")
               instance.each_key do |name|
                 res = properties_result&.children&.[](instance[name]&.path)&.[]name
-                forbidden << name.tap { puts "adding #{name}" } if res && annotation_exists?(res, key: only_key)
+                forbidden << name if res && annotation_exists?(res, key: only_key)
               end
             end
 
@@ -50,7 +50,7 @@ module Skooma
           def annotation_exists?(result, key:)
             return result if result.key == key && result.annotation
 
-            result.each_children do |child|
+            result.children[result.instance.path]&.each_value do |child|
               return child if annotation_exists?(child, key: key)
             end
 

data/lib/skooma/keywords/oas_3_1/schema.rb

@@ -17,7 +17,7 @@ module Skooma
         private
 
         def wrap_value(value)
-          JSONSkooma::JSONSchema.new(
+          Objects::Schema.new(
             value,
             key: key,
             parent: parent_schema,

data/lib/skooma/matchers/conform_response_schema.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "rack/utils"
+
 module Skooma
   module Matchers
     class ConformResponseSchema < ConformRequestSchema
@@ -37,7 +39,7 @@ module Skooma
       private
 
       def status_matches?
-        @mapped_response["response"]["status"] == @expected
+        @mapped_response["response"]["status"] == @expected_code
       end
     end
   end

data/lib/skooma/matchers/wrapper.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "digest"
 require "pathname"
 
 module Skooma
@@ -44,7 +45,7 @@ module Skooma
         end
       end
 
-      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "", enforce_access_modes: false, use_patterns_for_path_matching: false, **params)
+      def initialize(helper_methods_module, openapi_path, base_uri: "https://skoomarb.dev/", path_prefix: "", enforce_access_modes: false, use_patterns_for_path_matching: false, coverage_store: nil, **params)
         super()
 
         registry = create_test_registry
@@ -59,7 +60,10 @@ module Skooma
         @schema.path_prefix = path_prefix
         @schema.enforce_access_modes = enforce_access_modes
 
-        storage = Skooma::CoverageStore.new(
+        # Any object implementing CoverageStore's interface (load_data,
+        # save_data, clear) can be passed via `coverage_store:` — e.g. to
+        # write one file per parallel CI runner and merge afterwards.
+        storage = coverage_store || Skooma::CoverageStore.new(
           file_path: File.join(Dir.pwd, "tmp", "skooma_coverage_#{Digest::SHA256.hexdigest(source_uri)[0..8]}.json")
         )
         @coverage = Coverage.new(@schema, mode: params[:coverage], format: params[:coverage_format], storage: storage)

data/lib/skooma/objects/base.rb

@@ -3,6 +3,8 @@
 module Skooma
   module Objects
     class Base < JSONSkooma::JSONSchema
+      include ExternalRefs
+
       DEFAULT_OPTIONS = {
         registry: REGISTRY_NAME
       }.freeze

data/lib/skooma/objects/media_type.rb

@@ -6,9 +6,87 @@ module Skooma
     class MediaType < Base
       def kw_classes
         [
-          Keywords::OAS31::Schema
+          Keywords::Schema
         ]
       end
+
+      module Keywords
+        # Applies the Media Type Object's `encoding` field before schema
+        # validation. For `multipart/*` and `application/x-www-form-urlencoded`
+        # bodies, fields arrive as raw strings; a field whose `contentType` is
+        # a JSON media type (explicitly via `encoding`, or by the multipart
+        # default for object-typed properties) is decoded first, so its schema
+        # validates the structured value rather than the serialized string.
+        class Schema < Skooma::Keywords::OAS31::Schema
+          self.key = "schema"
+
+          URLENCODED = "application/x-www-form-urlencoded"
+
+          def evaluate(instance, result)
+            super(apply_encoding(instance), result)
+          end
+
+          private
+
+          def apply_encoding(instance)
+            return instance unless form_media_type?
+
+            value = instance.value
+            return instance unless value.is_a?(Hash)
+
+            encoding = parent_schema["encoding"]
+            decoded = value.each_with_object({}) do |(field, field_value), hash|
+              hash[field] = decode_field(field, field_value, encoding)
+            end
+
+            Instance::Attribute.new(decoded, key: instance.key, parent: instance.parent)
+          end
+
+          def media_type
+            parent_schema.key.to_s.split(";").first.to_s.strip.downcase
+          end
+
+          def form_media_type?
+            media_type.start_with?("multipart/") || media_type == URLENCODED
+          end
+
+          def decode_field(field, value, encoding)
+            content_type = field_content_type(field, encoding)
+            return value unless json_media_type?(content_type)
+
+            parser = BodyParsers[content_type]
+            case value
+            when String
+              parser.call(value)
+            when Array
+              value.map { |item| item.is_a?(String) ? parser.call(item) : item }
+            else
+              value
+            end
+          end
+
+          def field_content_type(field, encoding)
+            explicit = encoding&.[](field)&.[]("contentType")&.value
+            return explicit if explicit
+
+            # The spec's default contentType for multipart object-typed
+            # properties is application/json.
+            return unless media_type.start_with?("multipart/")
+
+            property = json["properties"]&.[](field)
+            return unless property.is_a?(JSONSkooma::JSONSchema)
+
+            "application/json" if property["type"]&.value == "object"
+          end
+
+          def json_media_type?(content_type)
+            return false if content_type.nil?
+
+            normalized = content_type.split(";").first.to_s.strip.downcase
+            normalized == "application/json" || normalized.end_with?("+json")
+          end
+        end
+      end
     end
   end
 end

data/lib/skooma/objects/parameter/keywords/content.rb

@@ -13,7 +13,25 @@ module Skooma
           def evaluate(instance, result)
             return if instance.value.nil?
 
-            super(ValueParser.call(instance, result), result)
+            value = ValueParser.call(instance, result)
+            return result.discard if value.nil?
+
+            # A parameter's `content` declares the media type its value is
+            # serialized in (typically exactly one entry). Parse the raw value
+            # with the matching body parser, then validate the parsed value
+            # against that media type's schema. (The header version picks the
+            # media type from the response Content-Type, which is wrong here.)
+            json.each do |media_type, media_type_object|
+              parsed = Instance::Attribute.new(
+                BodyParsers[media_type].call(value.value),
+                key: value.key,
+                parent: value.parent
+              )
+              result.call(parsed, media_type) do |media_type_result|
+                media_type_object.evaluate(parsed, media_type_result)
+                result.failure("Invalid content for media type #{media_type}") unless media_type_result.passed?
+              end
+            end
           end
         end
       end

data/lib/skooma/objects/parameter/keywords/required.rb

@@ -9,7 +9,10 @@ module Skooma
           self.depends_on = %w[in name style explode allowReserved allowEmptyValue]
 
           def evaluate(instance, result)
-            if json.value && ValueParser.call(instance, result)&.value.nil?
+            return unless json.value
+
+            value = ValueParser.call(instance, result, schema: parent_schema["schema"])
+            if value&.value.nil?
               result.failure("Parameter is required")
             end
           end

data/lib/skooma/objects/parameter/keywords/schema.rb

@@ -9,10 +9,13 @@ module Skooma
           self.depends_on = %w[in name style explode allowReserved allowEmptyValue]
 
           def evaluate(instance, result)
-            value = ValueParser.call(instance, result)
+            value = ValueParser.call(instance, result, schema: json)
             return result.discard if value.nil?
 
-            super(value, result)
+            # Parameters coerce deeply (their values arrive as all-strings);
+            # bodies keep OAS31::Schema's shallow `coerce`, so body validation
+            # is unaffected.
+            json.evaluate(value.deep_coerce(json), result)
           end
         end
       end

data/lib/skooma/objects/parameter/keywords/value_parser.rb

@@ -7,72 +7,302 @@ module Skooma
     class Parameter
       module Keywords
         module ValueParser
+          # https://spec.openapis.org/oas/v3.1.0#style-values
+          ARRAY_STYLE_DELIMITERS = {
+            "form" => ",",
+            "simple" => ",",
+            "spaceDelimited" => " ",
+            "pipeDelimited" => "|"
+          }.freeze
+
+          # Default `style` per parameter location (OpenAPI 3.1 parameter object).
+          DEFAULT_STYLE = {
+            "query" => "form",
+            "path" => "simple",
+            "header" => "simple",
+            "cookie" => "form"
+          }.freeze
+
           class << self
-            def call(instance, result)
-              type = result.sibling(instance, "in")&.annotation
-              raise Error, "Missing `in` key #{result.path}" unless type
+            def call(instance, result, schema: nil)
+              location = result.sibling(instance, "in")&.annotation
+              raise Error, "Missing `in` key #{result.path}" unless location
 
               key = result.sibling(instance, "name")&.annotation
               raise Error, "Missing `name` key #{result.path}" unless key
 
-              case type
+              case location
               when "query"
-                parse_query(instance)[key]
+                query_param_value(instance, result, key, schema: schema)
               when "header"
-                instance["headers"][key]
+                header_param_value(instance, result, key, schema: schema)
               when "path"
-                path_item_result = result.parent
-                path_item_result = path_item_result.parent until path_item_result.key.start_with?("/")
-
-                Instance::Attribute.new(
-                  path_item_result.annotation["path_attributes"][key],
-                  key: "path",
-                  parent: instance["path"]
-                )
+                path_param_value(instance, result, key, schema: schema)
               when "cookie"
-                # instance["headers"]["Cookie"]
+                cookie_param_value(instance, result, key, schema: schema)
               else
-                raise Error, "Unknown location: #{type}"
+                raise Error, "Unknown location: #{location}"
               end
             end
 
             private
 
-            def parse_query(instance)
-              params = {}
-              instance["query"]&.value.to_s.split(/[&;]/).each do |pairs|
-                key, value = pairs.split("=", 2).collect { |v| CGI.unescape(v) }
-                next unless key
+            # The declared shape of the parameter value: :array, :object, or
+            # :primitive (scalars, missing schemas, and `content` params).
+            def shape_of(schema)
+              return :primitive unless schema.is_a?(JSONSkooma::JSONSchema) && schema.type == "object"
+
+              case schema["type"]&.value
+              when "array" then :array
+              when "object" then :object
+              else :primitive
+              end
+            end
+
+            def query_param_value(instance, result, key, schema:)
+              shape = shape_of(schema)
 
-                params[key] = value
+              # `deepObject` spreads an object across bracketed keys
+              # (`filter[a]=1&filter[b]=2`) and is the only style that consumes
+              # more than one query key, so it is handled before the scalar/array
+              # path.
+              if result.sibling(instance, "style")&.annotation == "deepObject"
+                return deep_object_value(instance, key)
               end
 
+              if shape == :object
+                return form_object_value(instance, result, key, schema)
+              end
+
+              array = shape == :array
+              params = parse_query(instance["query"]&.value)
+              values = params[key]
+              # Support the non-standard Rails/Rack/PHP bracket convention
+              # (`ids[]=1&ids[]=2`) for array params declared as `name: ids`.
+              values = params["#{key}[]"] if values.nil? && array
+              return nil if values.nil?
+
+              value =
+                if array && !values.last.nil?
+                  deserialize_array(values, instance, result)
+                else
+                  # the last value wins for scalars and value-less keys (e.g. `?ids`)
+                  values.last
+                end
+
+              Instance::Attribute.new(value, key: key, parent: instance["query"])
+            end
+
+            # Header values are a single string; an array is delimited inline
+            # (`simple` style, comma-separated). `explode` does not change the
+            # serialization for headers, so it is not consulted. Object-valued
+            # headers are out of scope.
+            def header_param_value(instance, result, key, schema:)
+              attribute = instance["headers"][key]
+              return attribute unless shape_of(schema) == :array
+              return attribute if attribute.nil? || attribute.value.nil?
+
               Instance::Attribute.new(
-                params,
-                key: "query",
-                parent: instance["query"]
+                split_delimited(attribute.value, style_for(result, instance, "header")),
+                key: key,
+                parent: instance["headers"]
               )
             end
 
-            def style(value, instance, result)
-              case result.sibling(instance, "style")
-              when "simple"
-                value
+            # Path values are a single captured segment. `simple` (the default)
+            # is comma-delimited; `label` carries a `.` prefix and `matrix` a
+            # `;name=` prefix, and for arrays `explode` switches the item
+            # separator. Objects flatten into the segment as key/value pairs —
+            # comma-interleaved (`role,admin`) or `=`-joined (`role=admin`)
+            # when exploded.
+            def path_param_value(instance, result, key, schema:)
+              raw = path_attributes(result)[key]
+              return nil if raw.nil?
+
+              style = style_for(result, instance, "path")
+              explode = result.sibling(instance, "explode")&.annotation || false
+              value =
+                case shape_of(schema)
+                when :array
+                  deserialize_path_array(raw, key, style, explode)
+                when :object
+                  deserialize_path_object(raw, key, style, explode)
+                else
+                  strip_path_prefix(raw, key, style)
+                end
+
+              Instance::Attribute.new(value, key: "path", parent: instance["path"])
+            end
+
+            def path_attributes(result)
+              path_item_result = result.parent
+              path_item_result = path_item_result.parent until path_item_result.key.start_with?("/")
+              path_item_result.annotation["path_attributes"]
+            end
+
+            def strip_path_prefix(raw, name, style)
+              case style
+              when "label" then raw.delete_prefix(".")
+              when "matrix" then raw.delete_prefix(";#{name}=")
+              else raw
+              end
+            end
+
+            def deserialize_path_array(raw, name, style, explode)
+              case style
               when "label"
-                value.split(".")
+                strip_path_prefix(raw, name, style).split(explode ? "." : ",")
               when "matrix"
-                value.split(";")
-              when "form"
-                value.split("&")
-              when "spaceDelimited"
-                value.split(" ")
-              when "pipeDelimited"
-                value.split("|")
-              when "deepObject"
-                raise Error, "Not implemented yet"
+                if explode
+                  # `;id=3;id=4;id=5` — keep only this parameter's pairs
+                  raw.delete_prefix(";").split(";").map { |pair|
+                    pair_name, pair_value = pair.split("=", 2)
+                    pair_value if pair_name == name
+                  }.compact
+                else
+                  # `;id=3,4,5`
+                  strip_path_prefix(raw, name, style).split(",")
+                end
+              else # simple: `3,4,5`
+                raw.split(",")
+              end
+            end
+
+            # Object path params flatten properties into the segment:
+            #   simple:          `role,admin,name,Alex`
+            #   simple explode:  `role=admin,name=Alex`
+            #   label:           `.role,admin,name,Alex`
+            #   label explode:   `.role=admin.name=Alex`
+            #   matrix:          `;point=role,admin,name,Alex`
+            #   matrix explode:  `;role=admin;name=Alex`
+            # A malformed flattening (odd member count, missing `=`) returns the
+            # raw string so schema validation rejects it.
+            def deserialize_path_object(raw, name, style, explode)
+              members =
+                if explode
+                  body = (style == "matrix") ? raw.delete_prefix(";") : strip_path_prefix(raw, name, style)
+                  separator = {"label" => ".", "matrix" => ";"}.fetch(style, ",")
+                  body.split(separator).map { |pair| pair.split("=", 2) }
+                else
+                  strip_path_prefix(raw, name, style).split(",").each_slice(2).to_a
+                end
+
+              return raw unless members.all? { |pair| pair.size == 2 }
+
+              members.to_h
+            end
+
+            # Cookies carry one string per name; an array is a delimited inline
+            # value (`form` style, comma-separated). `explode` is not consulted
+            # because cookies cannot repeat a name. Object-valued cookies are
+            # out of scope.
+            def cookie_param_value(instance, result, key, schema:)
+              raw = parse_cookies(instance["headers"]["Cookie"]&.value)[key]
+              return nil if raw.nil?
+
+              value = (shape_of(schema) == :array) ? split_delimited(raw, style_for(result, instance, "cookie")) : raw
+              Instance::Attribute.new(value, key: key, parent: instance["headers"])
+            end
+
+            # deepObject: gather the bracketed properties of `key` into a hash.
+            # Property values stay strings; type coercion happens later via
+            # Instance#deep_coerce against the object's `properties` schema.
+            # (Nested objects and array-valued properties are out of scope.)
+            def deep_object_value(instance, key)
+              prefix = "#{key}["
+              object = {}
+              parse_query(instance["query"]&.value).each do |param_key, values|
+                next unless param_key.start_with?(prefix) && param_key.end_with?("]")
+
+                property = param_key.delete_prefix(prefix).delete_suffix("]")
+                next if property.empty?
+
+                object[property] = values.last
+              end
+              return nil if object.empty?
+
+              Instance::Attribute.new(object, key: key, parent: instance["query"])
+            end
+
+            # `form`-style object query params (the default style). Exploded
+            # objects drop the parameter name entirely — each declared property
+            # becomes its own query key (`?x=1&y=2`) — so members are gathered
+            # by matching the schema's `properties` names; `additionalProperties`
+            # members cannot be recognized and are out of scope. Non-exploded
+            # objects flatten under the parameter's own name (`?point=x,1,y,2`).
+            def form_object_value(instance, result, key, schema)
+              params = parse_query(instance["query"]&.value)
+              explode = result.sibling(instance, "explode")&.annotation
+              explode = true if explode.nil?
+
+              if explode
+                properties = schema["properties"]
+                return nil unless properties.respond_to?(:each)
+
+                object = {}
+                properties.each do |property, _subschema|
+                  values = params[property]
+                  object[property] = values.last unless values.nil?
+                end
+                return nil if object.empty?
+
+                Instance::Attribute.new(object, key: key, parent: instance["query"])
               else
-                raise Error, "Unknown style: #{result.sibling(instance, "style")}"
+                values = params[key]
+                return nil if values.nil? || values.last.nil?
+
+                members = values.last.split(",").each_slice(2).to_a
+                # A malformed flattening (odd member count) stays a raw string
+                # so schema validation rejects it.
+                value = (members.all? { |pair| pair.size == 2 }) ? members.to_h : values.last
+                Instance::Attribute.new(value, key: key, parent: instance["query"])
+              end
+            end
+
+            def parse_query(query_string)
+              params = {}
+              query_string.to_s.split(/[&;]/).each do |pair|
+                key, value = pair.split("=", 2).collect { |v| CGI.unescape(v) }
+                next unless key
+
+                (params[key] ||= []) << value
+              end
+
+              params
+            end
+
+            # Cookie values are opaque (RFC 6265): split into name=value pairs
+            # but do not percent-decode (unlike query strings), so values such as
+            # base64 tokens stay intact.
+            def parse_cookies(cookie_string)
+              cookies = {}
+              cookie_string.to_s.split(/;\s*/).each do |pair|
+                name, value = pair.split("=", 2)
+                next if name.nil? || name.empty?
+
+                cookies[name] = value
               end
+
+              cookies
+            end
+
+            def deserialize_array(values, instance, result)
+              style = style_for(result, instance, "query")
+              explode = result.sibling(instance, "explode")&.annotation
+              explode = style == "form" if explode.nil?
+
+              # exploded arrays are serialized as repeated keys (`ids=1&ids=2`)
+              return values.compact if explode
+
+              split_delimited(values.last, style)
+            end
+
+            def split_delimited(raw, style)
+              raw.split(ARRAY_STYLE_DELIMITERS.fetch(style, ","))
+            end
+
+            def style_for(result, instance, location)
+              result.sibling(instance, "style")&.annotation || DEFAULT_STYLE.fetch(location, "form")
             end
           end
         end

data/lib/skooma/objects/schema.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Skooma
+  module Objects
+    # JSON Schema value inside an OpenAPI `schema:` keyword. Subclass of
+    # JSONSkooma::JSONSchema that participates in external $ref resolution.
+    class Schema < JSONSkooma::JSONSchema
+      include ExternalRefs
+    end
+  end
+end

data/lib/skooma/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Skooma
-  VERSION = "0.3.8"
+  VERSION = "0.4.0"
 end

data/lib/skooma.rb

@@ -22,6 +22,7 @@ module Skooma
 
   JSONSkooma.register_dialect("oas-3.1", Dialects::OAS31)
   JSONSkooma::Formatters.register :skooma, OutputFormat
+  JSONSkooma::Keywords::ValueSchemas.default_schema_class = Objects::Schema
 
   class << self
     def create_registry(name: REGISTRY_NAME)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: skooma
 version: !ruby/object:Gem::Version
-  version: 0.3.8
+  version: 0.4.0
 platform: ruby
 authors:
 - Svyatoslav Kryukov
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: rack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
 - !ruby/object:Gem::Dependency
   name: zeitwerk
   requirement: !ruby/object:Gem::Requirement
@@ -29,14 +43,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.2.5
+        version: 0.2.7
 description: Apply a documentation-first approach to API development.
 email:
 - me@skryukov.dev
@@ -67,6 +81,7 @@ files:
 - lib/skooma/coverage_store.rb
 - lib/skooma/dialects/oas_3_1.rb
 - lib/skooma/env_mapper.rb
+- lib/skooma/external_refs.rb
 - lib/skooma/inflector.rb
 - lib/skooma/instance.rb
 - lib/skooma/keywords/oas_3_1.rb
@@ -145,6 +160,7 @@ files:
 - lib/skooma/objects/response/keywords/content.rb
 - lib/skooma/objects/response/keywords/headers.rb
 - lib/skooma/objects/response/keywords/links.rb
+- lib/skooma/objects/schema.rb
 - lib/skooma/output_format.rb
 - lib/skooma/rspec.rb
 - lib/skooma/validators/double.rb