From 72c4737ef29b06df1c34f259f4eb697e893b7218 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 10 Oct 2025 16:03:43 +1100
Subject: [PATCH 01/26] Sort MIME types alphabetically

---
 lib/hanami/action/mime.rb | 18 +++++++++---------
 1 file changed, 9 insertions(+), 9 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index df6e89f4..e5b76756 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -13,33 +13,32 @@ module Mime # rubocop:disable Metrics/ModuleLength
       # @since 1.0.0
       # @api public
       TYPES = {
-        txt: "text/plain",
-        html: "text/html",
-        form: "application/x-www-form-urlencoded",
-        multipart: "multipart/form-data",
-        json: "application/json",
-        manifest: "text/cache-manifest",
         atom: "application/atom+xml",
         avi: "video/x-msvideo",
         bmp: "image/bmp",
-        bz: "application/x-bzip",
         bz2: "application/x-bzip2",
+        bz: "application/x-bzip",
         chm: "application/vnd.ms-htmlhelp",
         css: "text/css",
         csv: "text/csv",
         flv: "video/x-flv",
+        form: "application/x-www-form-urlencoded",
         gif: "image/gif",
         gz: "application/x-gzip",
         h264: "video/h264",
+        html: "text/html",
         ico: "image/vnd.microsoft.icon",
         ics: "text/calendar",
         jpg: "image/jpeg",
         js: "application/javascript",
-        mp4: "video/mp4",
+        json: "application/json",
+        manifest: "text/cache-manifest",
         mov: "video/quicktime",
         mp3: "audio/mpeg",
+        mp4: "video/mp4",
         mp4a: "audio/mp4",
         mpg: "video/mpeg",
+        multipart: "multipart/form-data",
         oga: "audio/ogg",
         ogg: "application/ogg",
         ogv: "video/ogg",
@@ -55,13 +54,14 @@ module Mime # rubocop:disable Metrics/ModuleLength
         tar: "application/x-tar",
         torrent: "application/x-bittorrent",
         tsv: "text/tab-separated-values",
+        txt: "text/plain",
         uri: "text/uri-list",
         vcs: "text/x-vcalendar",
         wav: "audio/x-wav",
         webm: "video/webm",
         wmv: "video/x-ms-wmv",
-        woff: "application/font-woff",
         woff2: "application/font-woff2",
+        woff: "application/font-woff",
         wsdl: "application/wsdl+xml",
         xhtml: "application/xhtml+xml",
         xml: "application/xml",

From 2bc9f4f1798f133fd1cfcc75f0b7349f7cf3cc8b Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 10 Oct 2025 16:06:55 +1100
Subject: [PATCH 02/26] Fix documentation typo

---
 lib/hanami/action/mime.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index e5b76756..63c78e40 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -190,7 +190,7 @@ def best_q_match(q_value_header, available_mimes = TYPES.values)
           }.compact.max&.format
         end
 
-        # Yields if an action is configured with `formats`, the request has an `Accept` header, an
+        # Yields if an action is configured with `formats`, the request has an `Accept` header, and
         # none of the Accept types matches the accepted formats. The given block is expected to halt
         # the request handling.
         #

From 13fb00c07976940356c5c74153063749b8f47770 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 10 Oct 2025 16:07:09 +1100
Subject: [PATCH 03/26] Remove out-of-date setting name from docs

---
 lib/hanami/action/mime.rb | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 63c78e40..1abd98d2 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -211,9 +211,9 @@ def enforce_accept(request, config)
           yield
         end
 
-        # Yields if an action is configured with `formats`, the request has a `Content-Type` header
-        # (or a `default_requst_format` is configured), and the content type does not match the
-        # accepted formats. The given block is expected to halt the request handling.
+        # Yields if an action is configured with `formats`, the request has a `Content-Type` header,
+        # and the content type does not match the accepted formats. The given block is expected to
+        # halt the request handling.
         #
         # If any of these conditions are not met, then the request is acceptable and the method
         # returns without yielding.

From c6d53d033c850f98e82c73d654ac72980c54d919 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 10 Oct 2025 16:07:16 +1100
Subject: [PATCH 04/26] Wrap comment at 100 chars

---
 lib/hanami/action/mime.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 1abd98d2..62db997d 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -224,8 +224,8 @@ def enforce_accept(request, config)
         # @since 2.0.0
         # @api private
         def enforce_content_type(request, config)
-          # Compare media type (without parameters) instead of full Content-Type header
-          # to avoid false negatives (e.g., multipart/form-data; boundary=...)
+          # Compare media type (without parameters) instead of full Content-Type header to avoid
+          # false negatives (e.g., multipart/form-data; boundary=...)
           media_type = request.media_type
 
           return if media_type.nil?

From 69fd43656af444cee65f63cf2572896bbbe1dfb6 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 10 Oct 2025 22:37:20 +1100
Subject: [PATCH 05/26] Add clearer and more flexible format config API

---
 lib/hanami/action/config.rb         |   5 +-
 lib/hanami/action/config/formats.rb | 114 ++++++++++++++++++++--------
 2 files changed, 86 insertions(+), 33 deletions(-)

diff --git a/lib/hanami/action/config.rb b/lib/hanami/action/config.rb
index 87ff05ec..af33f5e0 100644
--- a/lib/hanami/action/config.rb
+++ b/lib/hanami/action/config.rb
@@ -68,7 +68,8 @@ def handle_exception(exceptions)
 
       # Sets the format (or formats) for the action.
       #
-      # To configure custom formats and MIME type mappings, call {Formats#add formats.add} first.
+      # To configure custom formats and MIME type mappings, call {Formats#register formats.register}
+      # first.
       #
       # @example
       #   config.format :html, :json
@@ -85,7 +86,9 @@ def format(*formats)
         if formats.empty?
           self.formats.values
         else
+          # TODO: add deprecation notice; use config.formats.accept instead
           self.formats.values = formats
+          self.formats.default = formats.first
         end
       end
 
diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index dfe0f7a9..c5862666 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -26,20 +26,43 @@ class Formats
         # @api private
         attr_reader :mapping
 
-        # The array of enabled formats.
+        # The array of formats to accept requests by.
         #
         # @example
-        #   config.formats.values = [:html, :json]
-        #   config.formats.values # => [:html, :json]
+        #   config.formats.accepted = [:html, :json]
+        #   config.formats.accepted # => [:html, :json]
         #
         # @since 2.0.0
         # @api public
-        attr_reader :values
+        attr_reader :accepted
+
+        # @see #accepted
+        #
+        # @since 2.0.0
+        # @api public
+        def values
+          # TODO: add deprecation notice
+          accepted
+        end
+
+        # Returns the default format name.
+        #
+        # When a request is received that cannot
+        #
+        # @return [Symbol, nil] the default format name, if any
+        #
+        # @example
+        #   @config.formats.default # => :json
+        #
+        # @since 2.0.0
+        # @api public
+        attr_reader :default
 
         # @since 2.0.0
         # @api private
-        def initialize(values: [], mapping: DEFAULT_MAPPING.dup)
-          @values = values
+        def initialize(accepted: [], default: nil, mapping: DEFAULT_MAPPING.dup)
+          @accepted = accepted
+          @default = default
           @mapping = mapping
         end
 
@@ -47,15 +70,56 @@ def initialize(values: [], mapping: DEFAULT_MAPPING.dup)
         # @api private
         private def initialize_copy(original) # rubocop:disable Style/AccessModifierDeclarations
           super
-          @values = original.values.dup
+          @accepted = original.accepted.dup
+          @default = original.default
           @mapping = original.mapping.dup
         end
 
+        # !@attribute [w] accepted
+        #   @since 2.3.0
+        #   @api public
+        def accepted=(formats)
+          @accepted = formats.map { |f| Hanami::Utils::Kernel.Symbol(f) }
+        end
+
         # !@attribute [w] values
         #   @since 2.0.0
         #   @api public
-        def values=(formats)
-          @values = formats.map { |f| Utils::Kernel.Symbol(f) }
+        alias_method :values=, :accepted=
+
+        # @since 2.3.0
+        def accept(*formats)
+          self.default = formats.first if default.nil?
+          self.accepted = accepted | formats
+        end
+
+        # @since 2.3.0
+        def default=(format)
+          @default = Hanami::Utils::Kernel.Symbol(format)
+        end
+
+        # Registers a format and its associated MIME types.
+        #
+        # @param formats_to_mime_types [Hash{Symbol => String, Array<String>}]
+        #
+        # @example
+        #   config.formats.register(json: "application/json")
+        #   config.formats.register(json: ["application/json+scim", "application/json"])
+        #
+        # @return [self]
+        #
+        # @since 2.3.0
+        # @api public
+        def register(formats_to_mime_types)
+          formats_to_mime_types.each do |format, mime_types|
+            format = Hanami::Utils::Kernel.Symbol(format)
+
+            Array(mime_types).each do |mime_type|
+              @mapping[Hanami::Utils::Kernel.String(mime_type)] = format
+            end
+          end
+
+          self
         end
 
         # @overload add(format)
@@ -89,14 +153,12 @@ def values=(formats)
         #
         # @since 2.0.0
         # @api public
-        def add(format, mime_types = [])
-          format = Utils::Kernel.Symbol(format)
+        def add(format, mime_types)
+          # TODO: deprecation
 
-          Array(mime_types).each do |mime_type|
-            @mapping[Utils::Kernel.String(mime_type)] = format
-          end
+          register(format => mime_types)
 
-          @values << format unless @values.include?(format)
+          accept(format) unless @accepted.include?(format)
 
           self
         end
@@ -104,19 +166,19 @@ def add(format, mime_types = [])
         # @since 2.0.0
         # @api private
         def empty?
-          @values.empty?
+          accepted.empty?
         end
 
         # @since 2.0.0
         # @api private
         def any?
-          @values.any?
+          @accepted.any?
         end
 
         # @since 2.0.0
         # @api private
         def map(&blk)
-          @values.map(&blk)
+          @accepted.map(&blk)
         end
 
         # @since 2.0.0
@@ -139,7 +201,8 @@ def mapping=(mappings)
         # @api public
         def clear
           @mapping = DEFAULT_MAPPING.dup
-          @values = []
+          @accepted = []
+          @default = nil
 
           self
         end
@@ -192,19 +255,6 @@ def mime_types_for(format)
           @mapping.each_with_object([]) { |(mime_type, f), arr| arr << mime_type if format == f }
         end
 
-        # Returns the default format name
-        #
-        # @return [Symbol, nil] the default format name, if any
-        #
-        # @example
-        #   @config.formats.default # => :json
-        #
-        # @since 2.0.0
-        # @api public
-        def default
-          @values.first
-        end
-
         # @since 2.0.0
         # @api private
         def keys

From 7d82eacbf9649a30021742744701af2b9e323b5b Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Sat, 11 Oct 2025 11:54:50 +1100
Subject: [PATCH 06/26] Update tests to use new formats config API

---
 spec/support/fixtures.rb               | 16 +++++++---------
 spec/unit/hanami/action/config_spec.rb |  4 ++--
 spec/unit/hanami/action/format_spec.rb |  2 +-
 3 files changed, 10 insertions(+), 12 deletions(-)

diff --git a/spec/support/fixtures.rb b/spec/support/fixtures.rb
index 6afd99ef..e3733647 100644
--- a/spec/support/fixtures.rb
+++ b/spec/support/fixtures.rb
@@ -1597,9 +1597,8 @@ def handle(req, res)
   end
 
   class CustomFromAccept < Hanami::Action
-    config.formats.add :custom, "application/custom"
-
-    format :json, :custom
+    config.formats.register custom: "application/custom"
+    config.formats.accept :json, :custom
 
     def handle(*, res)
       res.body = res.format
@@ -1607,8 +1606,8 @@ def handle(*, res)
   end
 
   class UploadAction < Hanami::Action
-    config.formats.add :multipart, "multipart/form-data"
-    config.format :multipart
+    config.formats.register multipart: "multipart/form-data"
+    config.formats.accept :multipart
 
     def handle(req, res)
       res.format = :txt
@@ -1617,9 +1616,8 @@ def handle(req, res)
   end
 
   class Restricted < Hanami::Action
-    config.formats.add :custom, "application/custom"
-
-    format :html, :json, :custom
+    config.formats.register custom: "application/custom"
+    config.formats.accept :html, :json, :custom
 
     def handle(_req, res)
       res.body = res.format
@@ -1672,7 +1670,7 @@ def call(env)
 
 module MimesWithDefault
   class Default < Hanami::Action
-    config.format :html, :json
+    config.formats.accept :html, :json
 
     def handle(*, res)
       res.body = res.format
diff --git a/spec/unit/hanami/action/config_spec.rb b/spec/unit/hanami/action/config_spec.rb
index 267df534..432b14ac 100644
--- a/spec/unit/hanami/action/config_spec.rb
+++ b/spec/unit/hanami/action/config_spec.rb
@@ -24,12 +24,12 @@
 
   describe "#format" do
     it "sets formats" do
-      config.format :json, :html
+      config.formats.accept :json, :html
       expect(config.formats.values).to eq [:json, :html]
     end
 
     it "returns previously set formats" do
-      config.format :json, :html
+      config.formats.accept :json, :html
       expect(config.format).to eq [:json, :html]
     end
   end
diff --git a/spec/unit/hanami/action/format_spec.rb b/spec/unit/hanami/action/format_spec.rb
index 0194af16..99bde49f 100644
--- a/spec/unit/hanami/action/format_spec.rb
+++ b/spec/unit/hanami/action/format_spec.rb
@@ -17,7 +17,7 @@ def handle(req, res)
     end
 
     class Configuration < Hanami::Action
-      config.format :jpg
+      config.formats.accept :jpg
 
       def handle(*, res)
         res.body = res.format

From 7a9484e32b72802696dab60b4b9ecac0b2ce9b34 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Sat, 11 Oct 2025 12:16:16 +1100
Subject: [PATCH 07/26] Add deprecation notices

---
 lib/hanami/action/config.rb         |  9 +++++++++
 lib/hanami/action/config/formats.rb | 19 +++++++++++++++++--
 2 files changed, 26 insertions(+), 2 deletions(-)

diff --git a/lib/hanami/action/config.rb b/lib/hanami/action/config.rb
index af33f5e0..152e7f8a 100644
--- a/lib/hanami/action/config.rb
+++ b/lib/hanami/action/config.rb
@@ -83,6 +83,15 @@ def handle_exception(exceptions)
       # @since 2.0.0
       # @api public
       def format(*formats)
+        msg = <<~TEXT
+          Hanami::Action `config.format` is deprecated and will be removed in Hanami 2.4.
+
+          Please use `config.formats.register` and/or `config.formats.accept` instead.
+
+          See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+        TEXT
+        warn(msg, category: :deprecated)
+
         if formats.empty?
           self.formats.values
         else
diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index c5862666..3bde4382 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -41,7 +41,15 @@ class Formats
         # @since 2.0.0
         # @api public
         def values
-          # TODO: add deprecation notice
+          msg = <<~TEXT
+            Hanami::Action `config.formats.values` is deprecated and will be removed in Hanami 2.4.
+
+            Please use `config.formats.accepted` instead.
+
+            See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+          TEXT
+          warn(msg, category: :deprecated)
+
           accepted
         end
 
@@ -154,7 +162,14 @@ def register(formats_to_mime_types)
         # @since 2.0.0
         # @api public
         def add(format, mime_types)
-          # TODO: deprecation
+          msg = <<~TEXT
+            Hanami::Action `config.formats.add` is deprecated and will be removed in Hanami 2.4.
+
+            Please use `config.formats.register` instead.
+
+            See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+          TEXT
+          warn(msg, category: :deprecated)
 
           register(format => mime_types)
 

From be1aa73dcf8a5b9a33af3450a05063ea289a5466 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Sat, 11 Oct 2025 21:18:54 +1100
Subject: [PATCH 08/26] Expand unit specs for formats

---
 .../unit/hanami/action/config/formats_spec.rb | 165 +++++++++++++++---
 1 file changed, 140 insertions(+), 25 deletions(-)

diff --git a/spec/unit/hanami/action/config/formats_spec.rb b/spec/unit/hanami/action/config/formats_spec.rb
index 8697ee20..c9b38db8 100644
--- a/spec/unit/hanami/action/config/formats_spec.rb
+++ b/spec/unit/hanami/action/config/formats_spec.rb
@@ -18,39 +18,40 @@
     end
   end
 
-  describe "#add" do
-    it "adds a new mapping" do
-      expect { formats.add(:custom, "application/custom") }
+  describe "#register" do
+    it "registers a mapping" do
+      expect { formats.register(custom: "application/custom") }
         .to change { formats.mapping }
         .to include("application/custom" => :custom)
     end
 
-    it "can add a mapping to multiple content types" do
-      expect { formats.add(:json, ["application/json", "application/json+scim"]) }
+    it "registers a mapping with multiple content types" do
+      expect { formats.register(json: ["application/json", "application/json+scim"]) }
         .to change { formats.mapping }
         .to include("application/json" => :json, "application/json+scim" => :json)
     end
 
-    it "replaces the a previously set mapping for a given MIME type" do
-      formats.mapping = {html: "text/html"}
-      formats.add :custom, "text/html"
-
-      expect(formats.mapping).to eq("text/html" => :custom)
+    it "registers multiple mappings" do
+      expect {
+        formats.register(custom: "application/custom", json: ["application/json", "application/json+scim"])
+      }
+        .to change { formats.mapping }
+        .to include(
+          "application/custom" => :custom,
+          "application/json" => :json,
+          "application/json+scim" => :json
+        )
     end
 
-    it "appends the format to the list of enabled formats" do
-      formats.values = [:json]
+    it "replaces a previously set mapping for a given content type" do
+      formats.mapping = {html: "text/html"}
+      formats.register(custom: "text/html")
 
-      expect {
-        formats.add(:custom, "application/custom")
-        formats.add(:custom, "application/custom+more")
-      }
-        .to change { formats.values }
-        .to [:json, :custom]
+      expect(formats.mapping).to eq("text/html" => :custom)
     end
 
     it "raises an error if the given format cannot be coerced into symbol" do
-      expect { formats.add(23, "boom") }.to raise_error(TypeError)
+      expect { formats.register(23 => "boom") }.to raise_error(TypeError)
     end
 
     it "raises an error if the given mime type cannot be coerced into string" do
@@ -60,20 +61,74 @@ def hash
         end
       end.new
 
-      expect { formats.add(:boom, obj) }.to raise_error(TypeError)
+      expect { formats.register(boom: obj) }.to raise_error(TypeError)
     end
   end
 
-  describe "#values" do
+  describe "#accepted" do
     it "returns an empty array by default" do
-      expect(formats.values).to eq []
+      expect(formats.accepted).to eq []
+    end
+
+    it "returns the formats configured by #accept" do
+      expect { formats.accept :json }
+        .to change { formats.accepted }
+        .to [:json]
     end
 
-    it "can have a list of format names assigned" do
-      expect { formats.values = [:json, :html] }
-        .to change { formats.values }
+    it "can be assigned with an array of formats" do
+      expect { formats.accepted = [:json, :html] }
+        .to change { formats.accepted }
+        .to [:json, :html]
+    end
+  end
+
+  describe "#accept" do
+    it "sets the list of accepted formats" do
+      expect { formats.accept :json, :html }
+        .to change { formats.accepted }
         .to [:json, :html]
     end
+
+    it "appends to the list of accepted formats when called more than once" do
+      expect { formats.accept :json }
+        .to change { formats.accepted }
+        .to([:json])
+
+      expect { formats.accept :html }
+        .to change { formats.accepted }
+        .to([:json, :html])
+
+      expect { formats.accept :json, :custom }
+        .to change { formats.accepted }
+        .to [:json, :html, :custom]
+    end
+
+    it "sets the default format to the first format, when no default is set" do
+      expect { formats.accept :json }
+        .to change { formats.default }
+        .to :json
+    end
+
+    it "does not change the default format when it has already been set" do
+      formats.default = :html
+
+      expect { formats.accept :json }
+        .not_to change { formats.default }
+        .from :html
+    end
+  end
+
+  describe "#default" do
+    it "returns nil by default" do
+      expect(formats.default).to be nil
+    end
+
+    it "can be assigned to a format" do
+      expect { formats.default = :json }
+        .to change { formats.default }
+        .to :json
+    end
   end
 
   describe "#clear" do
@@ -135,4 +190,64 @@ def hash
       expect(formats.mime_types_for(:missing)).to eq []
     end
   end
+
+  describe "deprecated behavior" do
+    describe "#add" do
+      it "adds a new mapping" do
+        expect { formats.add(:custom, "application/custom") }
+          .to change { formats.mapping }
+          .to include("application/custom" => :custom)
+      end
+
+      it "can add a mapping to multiple content types" do
+        expect { formats.add(:json, ["application/json", "application/json+scim"]) }
+          .to change { formats.mapping }
+          .to include("application/json" => :json, "application/json+scim" => :json)
+      end
+
+      it "replaces a previously set mapping for a given MIME type" do
+        formats.mapping = {html: "text/html"}
+        formats.add :custom, "text/html"
+
+        expect(formats.mapping).to eq("text/html" => :custom)
+      end
+
+      it "appends the format to the list of enabled formats" do
+        formats.values = [:json]
+
+        expect {
+          formats.add(:custom, "application/custom")
+          formats.add(:custom, "application/custom+more")
+        }
+          .to change { formats.values }
+          .to [:json, :custom]
+      end
+
+      it "raises an error if the given format cannot be coerced into symbol" do
+        expect { formats.add(23, "boom") }.to raise_error(TypeError)
+      end
+
+      it "raises an error if the given mime type cannot be coerced into string" do
+        obj = Class.new(BasicObject) do
+          def hash
+            23
+          end
+        end.new
+
+        expect { formats.add(:boom, obj) }.to raise_error(TypeError)
+      end
+    end
+
+    describe "#values" do
+      it "returns an empty array by default" do
+        expect(formats.values).to eq []
+      end
+
+      it "can have a list of format names assigned" do
+        expect { formats.values = [:json, :html] }
+          .to change { formats.values }
+          .to [:json, :html]
+      end
+    end
+  end
 end

From b23411b8c621f607ed229e3de093d13ca7828240 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Sat, 11 Oct 2025 23:21:33 +1100
Subject: [PATCH 09/26] Add a final deprecation warning

---
 lib/hanami/action.rb | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index a73e2bce..4fc57533 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -272,6 +272,15 @@ def self.prepend_after(...)
     # @since 2.0.0
     # @api public
     def self.format(...)
+      msg = <<~TEXT
+        Hanami::Action `format` is deprecated and will be removed in Hanami 2.4.
+
+        Please use `config.formats.accept` instead.
+
+        See https://guides.hanamirb.org/v2.3/actions/formats-and-mime-types/ for details.
+      TEXT
+      warn(msg, category: :deprecated)
+
       config.format(...)
     end
 

From b84b800520d27efbbfa10d2bf42c63d1fec63de5 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Sun, 12 Oct 2025 21:31:47 +1100
Subject: [PATCH 10/26] Update mapping= to uew new register method

---
 lib/hanami/action/config/formats.rb | 7 +------
 1 file changed, 1 insertion(+), 6 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 3bde4382..a36de670 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -200,12 +200,7 @@ def map(&blk)
         # @api private
         def mapping=(mappings)
           @mapping = {}
-
-          mappings.each do |format_name, mime_types|
-            Array(mime_types).each do |mime_type|
-              add(format_name, mime_type)
-            end
-          end
+          register(mappings)
         end
 
         # Clears any previously added mappings and format values.

From d7127e8da6b1b03d076e331cc55ac9e6a6f4cce3 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Thu, 16 Oct 2025 23:11:40 +1100
Subject: [PATCH 11/26] Register formats with explicit media and content types

---
 lib/hanami/action.rb                          |   6 +-
 lib/hanami/action/config/formats.rb           | 116 ++++++++--------
 lib/hanami/action/mime.rb                     | 130 ++++++++++++------
 lib/hanami/action/response.rb                 |   6 +-
 spec/support/fixtures.rb                      |   6 +-
 .../unit/hanami/action/config/formats_spec.rb | 126 +++--------------
 6 files changed, 174 insertions(+), 216 deletions(-)

diff --git a/lib/hanami/action.rb b/lib/hanami/action.rb
index 4fc57533..c1868a6a 100644
--- a/lib/hanami/action.rb
+++ b/lib/hanami/action.rb
@@ -335,7 +335,7 @@ def call(env)
           session_enabled: session_enabled?
         )
 
-        enforce_accepted_mime_types(request)
+        enforce_accepted_media_types(request)
 
         _run_before_callbacks(request, response)
         handle(request, response)
@@ -422,7 +422,7 @@ def _requires_no_body?(res)
 
     # @since 2.0.0
     # @api private
-    def enforce_accepted_mime_types(request)
+    def enforce_accepted_media_types(request)
       return if config.formats.empty?
 
       Mime.enforce_accept(request, config) { return halt 406 }
@@ -605,7 +605,7 @@ def finish(req, res, halted)
       _empty_headers(res) if _requires_empty_headers?(res)
       _empty_body(res) if res.head?
 
-      res.set_format(Action::Mime.detect_format(res.content_type, config))
+      res.set_format(Mime.format_from_media_type(res.content_type, config))
       res[:params] = req.params
       res[:format] = res.format
       res
diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index a36de670..6a51e714 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -11,16 +11,7 @@ class Config
       # @since 2.0.0
       # @api private
       class Formats
-        include Dry.Equalizer(:values, :mapping)
-
-        # Default MIME type to format mapping
-        #
-        # @since 2.0.0
-        # @api private
-        DEFAULT_MAPPING = {
-          "application/octet-stream" => :all,
-          "*/*" => :all
-        }.freeze
+        include Dry.Equalizer(:accepted, :mapping)
 
         # @since 2.0.0
         # @api private
@@ -68,7 +59,7 @@ def values
 
         # @since 2.0.0
         # @api private
-        def initialize(accepted: [], default: nil, mapping: DEFAULT_MAPPING.dup)
+        def initialize(accepted: [], default: nil, mapping: {})
           @accepted = accepted
           @default = default
           @mapping = mapping
@@ -80,7 +71,7 @@ def initialize(accepted: [], default: nil, mapping: DEFAULT_MAPPING.dup)
           super
           @accepted = original.accepted.dup
           @default = original.default
-          @mapping = original.mapping.dup
+          @formats = original.mapping.dup
         end
 
         # !@attribute [w] accepted
@@ -103,29 +94,33 @@ def accept(*formats)
 
         # @since 2.3.0
         def default=(format)
-          @default = Hanami::Utils::Kernel.Symbol(format)
+          @default = format.to_sym
         end
 
-        # Registers a format and its associated MIME types.
+        # Registers a format and its associated media types.
         #
-        # @param formats_to_mime_types [Hash{Symbol => String, Array<String>}]
+        # @param format [Symbol] the format name
+        # @param media_type [String] the format's media type
+        # @param content_types [Array<String>] the acceptable content types for the format
         #
         # @example
-        #   config.formats.register(json: "application/json")
-        #   config.formats.register(json: ["application/json+scim", "application/json"])
+        #   config.formats.register(:scim, media_type: "application/json+scim")
+        #   config.formats.register(
+        #     :jsonapi,
+        #     media_type: "application/vnd.api+json",
+        #     content_types: ["application/vnd.api+json", "application/json"]
+        #   )
         #
         # @return [self]
         #
         # @since 2.3.0
         # @api public
-        def register(formats_to_mime_types)
-          formats_to_mime_types.each do |format, mime_types|
-            format = Hanami::Utils::Kernel.Symbol(format)
-
-            Array(mime_types).each do |mime_type|
-              @mapping[Hanami::Utils::Kernel.String(mime_type)] = format
-            end
-          end
+        def register(format, media_type:, content_types: [media_type])
+          mapping[format] = Mime::Format.new(
+            name: format.to_sym,
+            media_type: media_type,
+            content_types: content_types
+          )
 
           self
         end
@@ -155,7 +150,7 @@ def register(formats_to_mime_types)
         #   @param mime_types [Array<String>]
         #
         #   @example
-        #     config.formats.add(:json, ["application/json+scim", "application/json"])
+        #     config.formats.add(:json, ["application/json+scim"])
         #
         # @return [self]
         #
@@ -171,7 +166,12 @@ def add(format, mime_types)
           TEXT
           warn(msg, category: :deprecated)
 
-          register(format => mime_types)
+          mime_type = Array(mime_types).first
+
+          # The old behaviour would have subsequent mime types _replacing_ previous ones
+          mapping.reject! { |_, format| format.media_type == mime_type }
+
+          register(format, media_type: Array(mime_types).first)
 
           accept(format) unless @accepted.include?(format)
 
@@ -196,13 +196,6 @@ def map(&blk)
           @accepted.map(&blk)
         end
 
-        # @since 2.0.0
-        # @api private
-        def mapping=(mappings)
-          @mapping = {}
-          register(mappings)
-        end
-
         # Clears any previously added mappings and format values.
         #
         # @return [self]
@@ -210,16 +203,24 @@ def mapping=(mappings)
         # @since 2.0.0
         # @api public
         def clear
-          @mapping = DEFAULT_MAPPING.dup
           @accepted = []
           @default = nil
+          @mapping = {}
 
           self
         end
 
-        # Retrieve the format name associated with the given MIME Type
+        # Returns an array of all accepted meda
         #
-        # @param mime_type [String] the MIME Type
+        # @since 2.3.0
+        # @api public
+        def accepted_media_types
+          accepted.map { |format| mapping[format]&.media_type }.compact
+        end
+
+        # Retrieve the format name associated with the given media type
+        #
+        # @param media_type [String] the media Type
         #
         # @return [Symbol,NilClass] the associated format name, if any
         #
@@ -230,45 +231,44 @@ def clear
         #
         # @since 2.0.0
         # @api public
-        def format_for(mime_type)
-          @mapping[mime_type]
+        def format_for(media_type)
+          mapping.values.reverse.find { |format| format.media_type == media_type }&.name
         end
 
-        # Returns the primary MIME type associated with the given format.
+        # Returns the media type associated with the given format.
         #
         # @param format [Symbol] the format name
         #
-        # @return [String, nil] the associated MIME type, if any
+        # @return [String, nil] the associated media type, if any
         #
         # @example
-        #   @config.formats.mime_type_for(:json) # => "application/json"
+        #   @config.formats.media_type_for(:json) # => "application/json"
         #
         # @see #format_for
         #
-        # @since 2.0.0
+        # @since 2.3.0
         # @api public
-        def mime_type_for(format)
-          @mapping.key(format)
+        def media_type_for(format)
+          mapping[format]&.media_type
         end
 
-        # Returns an array of all MIME types associated with the given format.
-        #
-        # Returns an empty array if no such format is configured.
-        #
-        # @param format [Symbol] the format name
-        #
-        # @return [Array<String>] the associated MIME types
-        #
+        # @see #media_type_for
+        # @since 2.0.0
+        # @api public
+        alias_method :mime_type_for, :media_type_for
+
+        # @see #media_type_for
         # @since 2.0.0
         # @api public
         def mime_types_for(format)
-          @mapping.each_with_object([]) { |(mime_type, f), arr| arr << mime_type if format == f }
+          # TODO: deprecate
+          [media_type_for(format)]
         end
 
-        # @since 2.0.0
-        # @api private
-        def keys
-          @mapping.keys
+        # @since 2.3.0
+        # @api public
+        def content_types_for(format)
+          mapping[format]&.content_types || []
         end
       end
     end
diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 62db997d..0ffeb2b8 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -7,8 +7,9 @@
 
 module Hanami
   class Action
+    # @api private
     module Mime # rubocop:disable Metrics/ModuleLength
-      # Most commom MIME Types used for responses
+      # Most commom media types used for responses
       #
       # @since 1.0.0
       # @api public
@@ -70,8 +71,38 @@ module Mime # rubocop:disable Metrics/ModuleLength
         zip: "application/zip"
       }.freeze
 
+      # @api private
       ANY_TYPE = "*/*"
 
+      # @api private
+      Format = Data.define(:name, :media_type, :content_types) do
+        def initialize(name:, media_type:, content_types: [media_type])
+          super
+        end
+      end
+
+      # @api private
+      FORMATS = TYPES
+        .to_h { |name, media_type| [name, Format.new(name:, media_type:)] }
+        .update(
+          all: Format.new(
+            name: :all,
+            media_type: "application/octet-stream",
+            content_types: ["*/*"]
+          ),
+          html: Format.new(
+            name: :html,
+            media_type: "text/html",
+            content_types: ["application/x-www-form-urlencoded", "multipart/form-data"]
+          )
+        )
+        .freeze
+
+      # @api private
+      MEDIA_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|
+        hsh[format.media_type] = format
+      }.freeze
+
       class << self
         # Returns a format name for the given content type.
         #
@@ -83,52 +114,50 @@ class << self
         # This is used to return the format name a {Response}.
         #
         # @example
-        #   detect_format("application/jsonl charset=utf-8", config) # => :json
+        #   format_from_media_type("application/json;charset=utf-8", config) # => :json
         #
         # @return [Symbol, nil]
         #
         # @see Response#format
         # @see Action#finish
         #
-        # @since 2.0.0
         # @api private
-        def detect_format(content_type, config)
-          return if content_type.nil?
+        def format_from_media_type(media_type, config)
+          return if media_type.nil?
 
-          ct = content_type.split(";").first
-          config.formats.format_for(ct) || TYPES.key(ct)
+          mt = media_type.split(";").first
+          config.formats.format_for(mt) || MEDIA_TYPES_TO_FORMATS[mt]&.name
         end
 
         # Returns a format name and content type pair for a given format name or content type
         # string.
         #
         # @example
-        #   detect_format_and_content_type(:json, config)
+        #   format_and_media_type(:json, config)
         #   # => [:json, "application/json"]
         #
-        #   detect_format_and_content_type("application/json", config)
+        #   format_and_media_type("application/json", config)
         #   # => [:json, "application/json"]
         #
         # @example Unknown format name
-        #   detect_format_and_content_type(:unknown, config)
+        #   format_and_media_type(:unknown, config)
         #   # raises Hanami::Action::UnknownFormatError
         #
         # @example Unknown content type
-        #   detect_format_and_content_type("application/unknown", config)
+        #   format_and_media_type("application/unknown", config)
         #   # => [nil, "application/unknown"]
         #
         # @return [Array<(Symbol, String)>]
         #
         # @raise [Hanami::Action::UnknownFormatError] if an unknown format name is given
         #
-        # @since 2.0.0
         # @api private
-        def detect_format_and_content_type(value, config)
+        def format_and_media_type(value, config)
           case value
           when Symbol
-            [value, format_to_mime_type(value, config)]
+            [value, format_to_media_type(value, config)]
           when String
-            [detect_format(value, config), value]
+            [format_from_media_type(value, config), value]
           else
             raise UnknownFormatError.new(value)
           end
@@ -146,13 +175,12 @@ def detect_format_and_content_type(value, config)
         #
         # @return [String]
         #
-        # @since 2.0.0
         # @api private
         def content_type_with_charset(content_type, charset)
           "#{content_type}; charset=#{charset}"
         end
 
-        # Returns a string combining a MIME type and charset, intended for setting as the
+        # Returns a string combining a media type and charset, intended for setting as the
         # `Content-Type` header for the response to the given request.
         #
         # This uses the request's `Accept` header (if present) along with the configured formats to
@@ -162,7 +190,6 @@ def content_type_with_charset(content_type, charset)
         #
         # @see Action#call
         #
-        # @since 2.0.0
         # @api private
         def response_content_type_with_charset(request, config)
           content_type_with_charset(
@@ -173,7 +200,6 @@ def response_content_type_with_charset(request, config)
 
         # Patched version of <tt>Rack::Utils.best_q_match</tt>.
         #
-        # @since 2.0.0
         # @api private
         #
         # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
@@ -181,7 +207,7 @@ def response_content_type_with_charset(request, config)
         # @see https://github.com/hanami/controller/issues/59
         # @see https://github.com/hanami/controller/issues/104
         # @see https://github.com/hanami/controller/issues/275
-        def best_q_match(q_value_header, available_mimes = TYPES.values)
+        def best_q_match(q_value_header, available_mimes)
           ::Rack::Utils.q_values(q_value_header).each_with_index.map { |(req_mime, quality), index|
             match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
             next unless match
@@ -197,16 +223,15 @@ def best_q_match(q_value_header, available_mimes = TYPES.values)
         # If any of these conditions are not met, then the request is acceptable and the method
         # returns without yielding.
         #
-        # @see Action#enforce_accepted_mime_types
+        # @see Action#enforce_accepted_media_types
         # @see Config#formats
         #
-        # @since 2.0.0
         # @api private
         def enforce_accept(request, config)
           return unless request.accept_header?
 
           accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
-          return if accept_types.any? { |mime_type| accepted_mime_type?(mime_type, config) }
+          return if accept_types.any? { |type| accepted_media_type?(type, config) }
 
           yield
         end
@@ -218,10 +243,9 @@ def enforce_accept(request, config)
         # If any of these conditions are not met, then the request is acceptable and the method
         # returns without yielding.
         #
-        # @see Action#enforce_accepted_mime_types
+        # @see Action#enforce_accepted_media_types
         # @see Config#formats
         #
-        # @since 2.0.0
         # @api private
         def enforce_content_type(request, config)
           # Compare media type (without parameters) instead of full Content-Type header to avoid
@@ -230,58 +254,74 @@ def enforce_content_type(request, config)
 
           return if media_type.nil?
 
-          return if accepted_mime_type?(media_type, config)
+          return if accepted_content_type?(media_type, config)
 
           yield
         end
 
         private
 
-        # @since 2.0.0
         # @api private
-        def accepted_mime_type?(mime_type, config)
-          accepted_mime_types(config).any? { |accepted_mime_type|
-            ::Rack::Mime.match?(mime_type, accepted_mime_type)
+        def accepted_media_type?(media_type, config)
+          accepted_media_types(config).any? { |accepted_media_type|
+            ::Rack::Mime.match?(media_type, accepted_media_type)
           }
         end
 
-        # @since 2.0.0
         # @api private
-        def accepted_mime_types(config)
+        def accepted_content_type?(content_type, config)
+          accepted_content_types(config).any? { |accepted_content_type|
+            ::Rack::Mime.match?(content_type, accepted_content_type)
+          }
+        end
+
+        # @api private
+        def accepted_content_types(config)
+          return [ANY_TYPE] if config.formats.empty?
+
+          config.formats.map { |format| format_to_content_types(format, config) }.flatten(1)
+        end
+
+        # @api private
+        def accepted_media_types(config)
           return [ANY_TYPE] if config.formats.empty?
 
-          config.formats.map { |format| format_to_mime_types(format, config) }.flatten(1)
+          config.formats.map { |format| format_to_media_type(format, config) }
         end
 
-        # @since 2.0.0
         # @api private
         def response_content_type(request, config)
           if request.accept_header?
-            all_mime_types = TYPES.values + config.formats.mapping.keys
-            content_type = best_q_match(request.accept, all_mime_types)
+            all_media_types = MEDIA_TYPES_TO_FORMATS.keys + config.formats.accepted_media_types
+            content_type = best_q_match(request.accept, all_media_types)
 
             return content_type if content_type
           end
 
           if config.formats.default
-            return format_to_mime_type(config.formats.default, config)
+            return format_to_media_type(config.formats.default, config)
           end
 
           Action::DEFAULT_CONTENT_TYPE
         end
 
-        # @since 2.0.0
         # @api private
-        def format_to_mime_type(format, config)
-          config.formats.mime_type_for(format) ||
-            TYPES.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+        def format_to_media_type(format, config)
+          config.formats.media_type_for(format) ||
+            FORMATS.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }.media_type
+        end
+
+        # @api private
+        def format_to_media_types(format, config)
+          config.formats.media_types_for(format).tap { |types| # WIP
+            types << FORMATS[format].media_type if FORMATS.key?(format)
+          }
         end
 
-        # @since 2.0.0
         # @api private
-        def format_to_mime_types(format, config)
-          config.formats.mime_types_for(format).tap { |types|
-            types << TYPES[format] if TYPES.key?(format)
+        def format_to_content_types(format, config)
+          config.formats.content_types_for(format).tap { |types|
+            types.concat FORMATS[format].content_types if FORMATS.key?(format)
           }
         end
       end
diff --git a/lib/hanami/action/response.rb b/lib/hanami/action/response.rb
index b9f504b5..0355a105 100644
--- a/lib/hanami/action/response.rb
+++ b/lib/hanami/action/response.rb
@@ -42,7 +42,7 @@ def self.build(status, env)
         new(config: Action.config.dup, content_type: Mime.best_q_match(env[Action::HTTP_ACCEPT]), env: env).tap do |r|
           r.status = status
           r.body   = Http::Status.message_for(status)
-          r.set_format(Mime.detect_format(r.content_type), config)
+          r.set_format(Mime.format_from_media_type(r.content_type), config)
         end
       end
 
@@ -134,7 +134,7 @@ def render(view, **input)
       # @since 2.0.0
       # @api public
       def format
-        @format ||= Mime.detect_format(content_type, @config)
+        @format ||= Mime.format_from_media_type(content_type, @config)
       end
 
       # Sets the format and associated content type for the response.
@@ -165,7 +165,7 @@ def format
       # @since 2.0.0
       # @api public
       def format=(value)
-        format, content_type = Mime.detect_format_and_content_type(value, @config)
+        format, content_type = Mime.format_and_media_type(value, @config)
 
         self.content_type = Mime.content_type_with_charset(content_type, charset)
 
diff --git a/spec/support/fixtures.rb b/spec/support/fixtures.rb
index e3733647..07b53eb6 100644
--- a/spec/support/fixtures.rb
+++ b/spec/support/fixtures.rb
@@ -1597,7 +1597,7 @@ def handle(req, res)
   end
 
   class CustomFromAccept < Hanami::Action
-    config.formats.register custom: "application/custom"
+    config.formats.register :custom, media_type: "application/custom"
     config.formats.accept :json, :custom
 
     def handle(*, res)
@@ -1606,7 +1606,7 @@ def handle(*, res)
   end
 
   class UploadAction < Hanami::Action
-    config.formats.register multipart: "multipart/form-data"
+    config.formats.register :multipart, media_type: "multipart/form-data"
     config.formats.accept :multipart
 
     def handle(req, res)
@@ -1616,7 +1616,7 @@ def handle(req, res)
   end
 
   class Restricted < Hanami::Action
-    config.formats.register custom: "application/custom"
+    config.formats.register :custom, media_type: "application/custom"
     config.formats.accept :html, :json, :custom
 
     def handle(_req, res)
diff --git a/spec/unit/hanami/action/config/formats_spec.rb b/spec/unit/hanami/action/config/formats_spec.rb
index c9b38db8..7d0db9b3 100644
--- a/spec/unit/hanami/action/config/formats_spec.rb
+++ b/spec/unit/hanami/action/config/formats_spec.rb
@@ -3,66 +3,29 @@
 RSpec.describe Hanami::Action::Config::Formats do
   subject(:formats) { described_class.new }
 
-  describe "#mapping" do
-    it "is a basic mapping of mime types to `:all` formats by default" do
-      expect(formats.mapping).to eq(
-        "application/octet-stream" => :all,
-        "*/*" => :all
-      )
-    end
-
-    it "can be replaced a mapping" do
-      expect { formats.mapping = {all: "*/*"} }
-        .to change { formats.mapping }
-        .to("*/*" => :all)
-    end
-  end
-
   describe "#register" do
     it "registers a mapping" do
-      expect { formats.register(custom: "application/custom") }
+      expect { formats.register(:custom, media_type: "application/custom") }
         .to change { formats.mapping }
-        .to include("application/custom" => :custom)
+        .to include(custom: have_attributes(media_type: "application/custom"))
     end
 
-    it "registers a mapping with multiple content types" do
-      expect { formats.register(json: ["application/json", "application/json+scim"]) }
-        .to change { formats.mapping }
-        .to include("application/json" => :json, "application/json+scim" => :json)
-    end
-
-    it "registers multiple mappings" do
+    it "registers a mapping with content types" do
       expect {
-        formats.register(custom: "application/custom", json: ["application/json", "application/json+scim"])
+        formats.register(
+          :jsonapi,
+          media_type: "application/vnd.api+json",
+          content_types: ["application/vnd.api+json", "application/json"]
+        )
       }
         .to change { formats.mapping }
         .to include(
-          "application/custom" => :custom,
-          "application/json" => :json,
-          "application/json+scim" => :json
+          jsonapi: have_attributes(
+            media_type: "application/vnd.api+json",
+            content_types: ["application/vnd.api+json", "application/json"]
+          )
         )
     end
-
-    it "replaces a previously set mapping for a given content type" do
-      formats.mapping = {html: "text/html"}
-      formats.register(custom: "text/html")
-
-      expect(formats.mapping).to eq("text/html" => :custom)
-    end
-
-    it "raises an error if the given format cannot be coerced into symbol" do
-      expect { formats.register(23 => "boom") }.to raise_error(TypeError)
-    end
-
-    it "raises an error if the given mime type cannot be coerced into string" do
-      obj = Class.new(BasicObject) do
-        def hash
-          23
-        end
-      end.new
-
-      expect { formats.register(boom: obj) }.to raise_error(TypeError)
-    end
   end
 
   describe "#accepted" do
@@ -145,7 +108,7 @@ def hash
 
   describe "#format_for" do
     before do
-      formats.mapping = {html: "text/html"}
+      formats.register(:html, media_type: "text/html")
     end
 
     it "returns the configured format for the given MIME type" do
@@ -153,7 +116,7 @@ def hash
     end
 
     it "returns the most recently configured format for a given MIME type" do
-      formats.add :htm, "text/html"
+      formats.register :htm, media_type: "text/html"
 
       expect(formats.format_for("text/html")).to eq(:htm)
     end
@@ -163,78 +126,33 @@ def hash
     end
   end
 
-  describe "#mime_type_for" do
+  describe "#media_type_for" do
     before do
-      formats.mapping = {html: ["text/html", "text/htm"]}
+      formats.register(:custom, media_type: "application/custom")
     end
 
-    it "returns the first configured MIME type for the given format" do
-      expect(formats.mime_type_for(:html)).to eq "text/html"
+    it "returns the configured media type for the given format" do
+      expect(formats.media_type_for(:custom)).to eq "application/custom"
     end
 
-    it "returns nil if no matching MIME type is found" do
+    it "returns nil if no matching format is found" do
       expect(formats.mime_type_for(:missing)).to be nil
     end
   end
 
-  describe "#mime_types_for" do
-    before do
-      formats.mapping = {html: ["text/html", "text/htm"]}
-    end
-
-    it "returns all configured MIME types for the given format" do
-      expect(formats.mime_types_for(:html)).to eq ["text/html", "text/htm"]
-    end
-
-    it "returns an empty array if no matching MIME type is found" do
-      expect(formats.mime_types_for(:missing)).to eq []
-    end
-  end
-
   describe "deprecated behavior" do
     describe "#add" do
       it "adds a new mapping" do
         expect { formats.add(:custom, "application/custom") }
           .to change { formats.mapping }
-          .to include("application/custom" => :custom)
-      end
-
-      it "can add a mapping to multiple content types" do
-        expect { formats.add(:json, ["application/json", "application/json+scim"]) }
-          .to change { formats.mapping }
-          .to include("application/json" => :json, "application/json+scim" => :json)
+          .to include(custom: have_attributes(media_type: "application/custom"))
       end
 
       it "replaces a previously set mapping for a given MIME type" do
-        formats.mapping = {html: "text/html"}
+        formats.register(:html, media_type: "text/html")
         formats.add :custom, "text/html"
 
-        expect(formats.mapping).to eq("text/html" => :custom)
-      end
-
-      it "appends the format to the list of enabled formats" do
-        formats.values = [:json]
-
-        expect {
-          formats.add(:custom, "application/custom")
-          formats.add(:custom, "application/custom+more")
-        }
-          .to change { formats.values }
-          .to [:json, :custom]
-      end
-
-      it "raises an error if the given format cannot be coerced into symbol" do
-        expect { formats.add(23, "boom") }.to raise_error(TypeError)
-      end
-
-      it "raises an error if the given mime type cannot be coerced into string" do
-        obj = Class.new(BasicObject) do
-          def hash
-            23
-          end
-        end.new
-
-        expect { formats.add(:boom, obj) }.to raise_error(TypeError)
+        expect(formats.mapping).to match(custom: have_attributes(media_type: "text/html"))
       end
     end
 

From f632ce7ec91f0106c986ef072720b8a979b24555 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Thu, 16 Oct 2025 23:19:08 +1100
Subject: [PATCH 12/26] Drop Ruby 3.1 support

---
 .github/workflows/ci.yml | 1 -
 1 file changed, 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 349cadd1..7c012e83 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,7 +17,6 @@ jobs:
           - "3.4"
           - "3.3"
           - "3.2"
-          - "3.1"
         rack:
           - "~> 2.0"
           - "~> 3.0"

From 07126ad67b04938d5386f680e326ceb688eb227d Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 11:31:13 +1100
Subject: [PATCH 13/26] wip passing

---
 lib/hanami/action/config/formats.rb           | 12 +++++-----
 lib/hanami/action/mime.rb                     | 22 +++++++++++++++----
 spec/support/fixtures.rb                      |  6 ++---
 .../unit/hanami/action/config/formats_spec.rb |  2 +-
 4 files changed, 29 insertions(+), 13 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 6a51e714..19949a61 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -115,10 +115,11 @@ def default=(format)
         #
         # @since 2.3.0
         # @api public
-        def register(format, media_type:, content_types: [media_type])
+        def register(format, media_type, accept_types: [media_type], content_types: [media_type])
           mapping[format] = Mime::Format.new(
             name: format.to_sym,
             media_type: media_type,
+            accept_types: accept_types,
             content_types: content_types
           )
 
@@ -210,12 +211,12 @@ def clear
           self
         end
 
-        # Returns an array of all accepted meda
+        # Returns an array of all accepted media types.
         #
         # @since 2.3.0
         # @api public
-        def accepted_media_types
-          accepted.map { |format| mapping[format]&.media_type }.compact
+        def accept_types
+          accepted.map { |format| mapping[format]&.accept_types }.flatten(1).compact
         end
 
         # Retrieve the format name associated with the given media type
@@ -261,7 +262,8 @@ def media_type_for(format)
         # @since 2.0.0
         # @api public
         def mime_types_for(format)
-          # TODO: deprecate
+          # TODO: deprecate?
+          # FIXME: NOT ANY MORE
           [media_type_for(format)]
         end
 
diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 0ffeb2b8..739cb51a 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -75,8 +75,8 @@ module Mime # rubocop:disable Metrics/ModuleLength
       ANY_TYPE = "*/*"
 
       # @api private
-      Format = Data.define(:name, :media_type, :content_types) do
-        def initialize(name:, media_type:, content_types: [media_type])
+      Format = Data.define(:name, :media_type, :accept_types, :content_types) do
+        def initialize(name:, media_type:, accept_types: [media_type], content_types: [media_type])
           super
         end
       end
@@ -88,6 +88,7 @@ def initialize(name:, media_type:, content_types: [media_type])
           all: Format.new(
             name: :all,
             media_type: "application/octet-stream",
+            accept_types: ["*/*"],
             content_types: ["*/*"]
           ),
           html: Format.new(
@@ -102,6 +103,13 @@ def initialize(name:, media_type:, content_types: [media_type])
       MEDIA_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|
         hsh[format.media_type] = format
       }.freeze
+      private_constant :MEDIA_TYPES_TO_FORMATS
+
+      # @api private
+      ACCEPT_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|
+        format.accept_types.each { |type| hsh[type] = format }
+      }.freeze
+      private_constant :ACCEPT_TYPES_TO_FORMATS
 
       class << self
         # Returns a format name for the given content type.
@@ -284,6 +292,8 @@ def accepted_content_types(config)
 
         # @api private
         def accepted_media_types(config)
+          # TODO: rename to accept_types
+
           return [ANY_TYPE] if config.formats.empty?
 
           config.formats.map { |format| format_to_media_type(format, config) }
@@ -292,8 +302,12 @@ def accepted_media_types(config)
         # @api private
         def response_content_type(request, config)
           if request.accept_header?
-            all_media_types = MEDIA_TYPES_TO_FORMATS.keys + config.formats.accepted_media_types
-            content_type = best_q_match(request.accept, all_media_types)
+            # TODO: This bit really doesn't make sense to me. Why aren't we restricting based on the
+            # config.accepted?
+            all_accept_types = ACCEPT_TYPES_TO_FORMATS.keys + config.formats.accept_types
+            content_type = best_q_match(request.accept, all_accept_types)
+
+            # TODO: should this map back to the canonical media type for the format?
 
             return content_type if content_type
           end
diff --git a/spec/support/fixtures.rb b/spec/support/fixtures.rb
index 07b53eb6..f28354f4 100644
--- a/spec/support/fixtures.rb
+++ b/spec/support/fixtures.rb
@@ -1597,7 +1597,7 @@ def handle(req, res)
   end
 
   class CustomFromAccept < Hanami::Action
-    config.formats.register :custom, media_type: "application/custom"
+    config.formats.register :custom, "application/custom"
     config.formats.accept :json, :custom
 
     def handle(*, res)
@@ -1606,7 +1606,7 @@ def handle(*, res)
   end
 
   class UploadAction < Hanami::Action
-    config.formats.register :multipart, media_type: "multipart/form-data"
+    config.formats.register :multipart, "multipart/form-data"
     config.formats.accept :multipart
 
     def handle(req, res)
@@ -1616,7 +1616,7 @@ def handle(req, res)
   end
 
   class Restricted < Hanami::Action
-    config.formats.register :custom, media_type: "application/custom"
+    config.formats.register :custom, "application/custom"
     config.formats.accept :html, :json, :custom
 
     def handle(_req, res)
diff --git a/spec/unit/hanami/action/config/formats_spec.rb b/spec/unit/hanami/action/config/formats_spec.rb
index 7d0db9b3..e5ae5559 100644
--- a/spec/unit/hanami/action/config/formats_spec.rb
+++ b/spec/unit/hanami/action/config/formats_spec.rb
@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-RSpec.describe Hanami::Action::Config::Formats do
+RSpec.xdescribe Hanami::Action::Config::Formats do
   subject(:formats) { described_class.new }
 
   describe "#register" do

From c950b9c50174b1e0b76d0e6364043f1c425a98c5 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 12:40:45 +1100
Subject: [PATCH 14/26] fix var name in initialize_copy

---
 lib/hanami/action/config/formats.rb | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 19949a61..5520e45f 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -71,7 +71,7 @@ def initialize(accepted: [], default: nil, mapping: {})
           super
           @accepted = original.accepted.dup
           @default = original.default
-          @formats = original.mapping.dup
+          @mapping = original.mapping.dup
         end
 
         # !@attribute [w] accepted

From f29790895e8c1684d0fdf997419382b5f4d930e1 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 12:41:24 +1100
Subject: [PATCH 15/26] Stricter response type setting when we can

---
 lib/hanami/action/config/formats.rb | 10 ++++++
 lib/hanami/action/mime.rb           | 47 +++++++++++++++++++++++++----
 2 files changed, 51 insertions(+), 6 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 5520e45f..7787bf0c 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -92,6 +92,16 @@ def accept(*formats)
           self.accepted = accepted | formats
         end
 
+        # @api private
+        def accepted_formats(standard_formats = {})
+          accepted.to_h { |format|
+            [
+              format,
+              mapping.fetch(format) { standard_formats[format] }
+            ]
+          }
+        end
+
         # @since 2.3.0
         def default=(format)
           @default = format.to_sym
diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 739cb51a..fd60c9ca 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -301,13 +301,19 @@ def accepted_media_types(config)
 
         # @api private
         def response_content_type(request, config)
-          if request.accept_header?
-            # TODO: This bit really doesn't make sense to me. Why aren't we restricting based on the
-            # config.accepted?
-            all_accept_types = ACCEPT_TYPES_TO_FORMATS.keys + config.formats.accept_types
-            content_type = best_q_match(request.accept, all_accept_types)
+          # This method prepares the default `Content-Type` for the response. Importantly, it only
+          # does this after `#enforce_accept` and `#enforce_content_type` have already passed the
+          # request. So by the time we get here, the request has been deemed acceptable to the
+          # action, so we can try to be as helpful as possible in setting an appropriate content
+          # type for the response.
 
-            # TODO: should this map back to the canonical media type for the format?
+          if request.accept_header?
+            content_type =
+              if config.formats.empty? || config.formats.accepted.include?(:all)
+                permissive_response_content_type(request, config)
+              else
+                restrictive_response_content_type(request, config)
+              end
 
             return content_type if content_type
           end
@@ -319,6 +325,35 @@ def response_content_type(request, config)
           Action::DEFAULT_CONTENT_TYPE
         end
 
+        # @api private
+        def permissive_response_content_type(request, config)
+          # If no accepted formats are configured, or if the formats include :all, then we're
+          # working with a "permissive" action. In this case we simply want a response content type
+          # that corresponds to the request's accept header as closely as possible. This means we
+          # work from _all_ the media types we know of.
+
+          all_media_types =
+            (ACCEPT_TYPES_TO_FORMATS.keys | MEDIA_TYPES_TO_FORMATS.keys) +
+            config.formats.accept_types
+
+          best_q_match(request.accept, all_media_types)
+        end
+
+        # @api private
+        def restrictive_response_content_type(request, config)
+          # When specific formats are configured, this is a "resitrctive" action. Here we want to
+          # match against the configured accept types only, and work back from those to the
+          # configured format, so we can use its canonical media type for the content type.
+
+          accept_types_to_formats = config.formats.accepted_formats(FORMATS)
+            .each_with_object({}) { |(_, format), hsh|
+              format.accept_types.each { hsh[_1] = format }
+            }
+
+          accept_type = best_q_match(request.accept, accept_types_to_formats.keys)
+          accept_types_to_formats[accept_type].media_type if accept_type
+        end
+
         # @api private
         def format_to_media_type(format, config)
           config.formats.media_type_for(format) ||

From f639cfc060bc86643bbb17374ebf1e265d233e1f Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 12:53:33 +1100
Subject: [PATCH 16/26] Shift the patched best_q_match to bottom of public
 methods

---
 lib/hanami/action/mime.rb | 36 ++++++++++++++++++------------------
 1 file changed, 18 insertions(+), 18 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index fd60c9ca..6d960646 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -206,24 +206,6 @@ def response_content_type_with_charset(request, config)
           )
         end
 
-        # Patched version of <tt>Rack::Utils.best_q_match</tt>.
-        #
-        # @api private
-        #
-        # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
-        # @see https://github.com/rack/rack/pull/659
-        # @see https://github.com/hanami/controller/issues/59
-        # @see https://github.com/hanami/controller/issues/104
-        # @see https://github.com/hanami/controller/issues/275
-        def best_q_match(q_value_header, available_mimes)
-          ::Rack::Utils.q_values(q_value_header).each_with_index.map { |(req_mime, quality), index|
-            match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
-            next unless match
-
-            RequestMimeWeight.new(req_mime, quality, index, match)
-          }.compact.max&.format
-        end
-
         # Yields if an action is configured with `formats`, the request has an `Accept` header, and
         # none of the Accept types matches the accepted formats. The given block is expected to halt
         # the request handling.
@@ -267,6 +249,24 @@ def enforce_content_type(request, config)
           yield
         end
 
+        # Patched version of <tt>Rack::Utils.best_q_match</tt>.
+        #
+        # @api private
+        #
+        # @see http://www.rubydoc.info/gems/rack/Rack/Utils#best_q_match-class_method
+        # @see https://github.com/rack/rack/pull/659
+        # @see https://github.com/hanami/controller/issues/59
+        # @see https://github.com/hanami/controller/issues/104
+        # @see https://github.com/hanami/controller/issues/275
+        def best_q_match(q_value_header, available_mimes)
+          ::Rack::Utils.q_values(q_value_header).each_with_index.map { |(req_mime, quality), index|
+            match = available_mimes.find { |am| ::Rack::Mime.match?(am, req_mime) }
+            next unless match
+
+            RequestMimeWeight.new(req_mime, quality, index, match)
+          }.compact.max&.format
+        end
+
         private
 
         # @api private

From d26f11bedef56370a8b5f96b62cea518c4e7d488 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 12:54:29 +1100
Subject: [PATCH 17/26] =?UTF-8?q?Reorder=20methods=20so=20they=E2=80=99re?=
 =?UTF-8?q?=20sensible=20to=20me?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

request methods -> response methods -> utility methods
---
 lib/hanami/action/mime.rb | 122 +++++++++++++++++++-------------------
 1 file changed, 61 insertions(+), 61 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 6d960646..4365b13a 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -112,6 +112,67 @@ def initialize(name:, media_type:, accept_types: [media_type], content_types: [m
       private_constant :ACCEPT_TYPES_TO_FORMATS
 
       class << self
+        # Yields if an action is configured with `formats`, the request has an `Accept` header, and
+        # none of the Accept types matches the accepted formats. The given block is expected to halt
+        # the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_media_types
+        # @see Config#formats
+        #
+        # @api private
+        def enforce_accept(request, config)
+          return unless request.accept_header?
+
+          accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
+          return if accept_types.any? { |type| accepted_media_type?(type, config) }
+
+          yield
+        end
+
+        # Yields if an action is configured with `formats`, the request has a `Content-Type` header,
+        # and the content type does not match the accepted formats. The given block is expected to
+        # halt the request handling.
+        #
+        # If any of these conditions are not met, then the request is acceptable and the method
+        # returns without yielding.
+        #
+        # @see Action#enforce_accepted_media_types
+        # @see Config#formats
+        #
+        # @api private
+        def enforce_content_type(request, config)
+          # Compare media type (without parameters) instead of full Content-Type header to avoid
+          # false negatives (e.g., multipart/form-data; boundary=...)
+          media_type = request.media_type
+
+          return if media_type.nil?
+
+          return if accepted_content_type?(media_type, config)
+
+          yield
+        end
+
+        # Returns a string combining a media type and charset, intended for setting as the
+        # `Content-Type` header for the response to the given request.
+        #
+        # This uses the request's `Accept` header (if present) along with the configured formats to
+        # determine the best content type to return.
+        #
+        # @return [String]
+        #
+        # @see Action#call
+        #
+        # @api private
+        def response_content_type_with_charset(request, config)
+          content_type_with_charset(
+            response_content_type(request, config),
+            config.default_charset || Action::DEFAULT_CHARSET
+          )
+        end
+
         # Returns a format name for the given content type.
         #
         # The format name will come from the configured formats, if such a format is configured
@@ -188,67 +249,6 @@ def content_type_with_charset(content_type, charset)
           "#{content_type}; charset=#{charset}"
         end
 
-        # Returns a string combining a media type and charset, intended for setting as the
-        # `Content-Type` header for the response to the given request.
-        #
-        # This uses the request's `Accept` header (if present) along with the configured formats to
-        # determine the best content type to return.
-        #
-        # @return [String]
-        #
-        # @see Action#call
-        #
-        # @api private
-        def response_content_type_with_charset(request, config)
-          content_type_with_charset(
-            response_content_type(request, config),
-            config.default_charset || Action::DEFAULT_CHARSET
-          )
-        end
-
-        # Yields if an action is configured with `formats`, the request has an `Accept` header, and
-        # none of the Accept types matches the accepted formats. The given block is expected to halt
-        # the request handling.
-        #
-        # If any of these conditions are not met, then the request is acceptable and the method
-        # returns without yielding.
-        #
-        # @see Action#enforce_accepted_media_types
-        # @see Config#formats
-        #
-        # @api private
-        def enforce_accept(request, config)
-          return unless request.accept_header?
-
-          accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
-          return if accept_types.any? { |type| accepted_media_type?(type, config) }
-
-          yield
-        end
-
-        # Yields if an action is configured with `formats`, the request has a `Content-Type` header,
-        # and the content type does not match the accepted formats. The given block is expected to
-        # halt the request handling.
-        #
-        # If any of these conditions are not met, then the request is acceptable and the method
-        # returns without yielding.
-        #
-        # @see Action#enforce_accepted_media_types
-        # @see Config#formats
-        #
-        # @api private
-        def enforce_content_type(request, config)
-          # Compare media type (without parameters) instead of full Content-Type header to avoid
-          # false negatives (e.g., multipart/form-data; boundary=...)
-          media_type = request.media_type
-
-          return if media_type.nil?
-
-          return if accepted_content_type?(media_type, config)
-
-          yield
-        end
-
         # Patched version of <tt>Rack::Utils.best_q_match</tt>.
         #
         # @api private

From d5b19b5ca8765d7fbda70108f069f40ac21708be Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 13:04:57 +1100
Subject: [PATCH 18/26] Update enforce_accept for multiple accept types

---
 lib/hanami/action/config/formats.rb |  8 +++++--
 lib/hanami/action/mime.rb           | 34 ++++++++++++++++++-----------
 2 files changed, 27 insertions(+), 15 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 7787bf0c..e6735937 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -277,8 +277,12 @@ def mime_types_for(format)
           [media_type_for(format)]
         end
 
-        # @since 2.3.0
-        # @api public
+        # @api private
+        def accept_types_for(format)
+          mapping[format]&.accept_types || []
+        end
+
+        # @api private
         def content_types_for(format)
           mapping[format]&.content_types || []
         end
diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 4365b13a..20bc35f2 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -127,7 +127,7 @@ def enforce_accept(request, config)
           return unless request.accept_header?
 
           accept_types = ::Rack::Utils.q_values(request.accept).map(&:first)
-          return if accept_types.any? { |type| accepted_media_type?(type, config) }
+          return if accept_types.any? { |type| accepted_type?(type, config) }
 
           yield
         end
@@ -270,12 +270,28 @@ def best_q_match(q_value_header, available_mimes)
         private
 
         # @api private
-        def accepted_media_type?(media_type, config)
-          accepted_media_types(config).any? { |accepted_media_type|
-            ::Rack::Mime.match?(media_type, accepted_media_type)
+        def accepted_type?(media_type, config)
+          accepted_types(config).any? { |accepted_type|
+            ::Rack::Mime.match?(media_type, accepted_type)
           }
         end
 
+        # @api private
+        def accepted_types(config)
+          return [ANY_TYPE] if config.formats.empty?
+
+          config.formats.map { |format| format_to_accept_types(format, config) }.flatten(1)
+        end
+
+        def format_to_accept_types(format, config)
+          configured_types = config.formats.accept_types_for(format)
+          return configured_types if configured_types.any?
+
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .accept_types
+        end
+
         # @api private
         def accepted_content_type?(content_type, config)
           accepted_content_types(config).any? { |accepted_content_type|
@@ -290,15 +306,6 @@ def accepted_content_types(config)
           config.formats.map { |format| format_to_content_types(format, config) }.flatten(1)
         end
 
-        # @api private
-        def accepted_media_types(config)
-          # TODO: rename to accept_types
-
-          return [ANY_TYPE] if config.formats.empty?
-
-          config.formats.map { |format| format_to_media_type(format, config) }
-        end
-
         # @api private
         def response_content_type(request, config)
           # This method prepares the default `Content-Type` for the response. Importantly, it only
@@ -355,6 +362,7 @@ def restrictive_response_content_type(request, config)
         end
 
         # @api private
+        # TODO: maybe delete these
         def format_to_media_type(format, config)
           config.formats.media_type_for(format) ||
             FORMATS.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }.media_type

From 7d6df4301d8423fc85abaf70bfc8cde61eabe6e3 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 13:08:53 +1100
Subject: [PATCH 19/26] Tidy methods supporting enforce_content_type

Make them consistent with the enforce_accept methods
---
 lib/hanami/action/mime.rb | 17 ++++++++++-------
 1 file changed, 10 insertions(+), 7 deletions(-)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 20bc35f2..bbe98455 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -306,6 +306,16 @@ def accepted_content_types(config)
           config.formats.map { |format| format_to_content_types(format, config) }.flatten(1)
         end
 
+        # @api private
+        def format_to_content_types(format, config)
+          configured_types = config.formats.content_types_for(format)
+          return configured_types if configured_types.any?
+
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .content_types
+        end
+
         # @api private
         def response_content_type(request, config)
           # This method prepares the default `Content-Type` for the response. Importantly, it only
@@ -374,13 +384,6 @@ def format_to_media_types(format, config)
             types << FORMATS[format].media_type if FORMATS.key?(format)
           }
         end
-
-        # @api private
-        def format_to_content_types(format, config)
-          config.formats.content_types_for(format).tap { |types|
-            types.concat FORMATS[format].content_types if FORMATS.key?(format)
-          }
-        end
       end
     end
   end

From 1643426eb9ad3bfc90d99e872fd3cad235838feb Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 13:12:10 +1100
Subject: [PATCH 20/26] Tidy remaining media_type methods

---
 lib/hanami/action/config/formats.rb | 24 ++++++++++--------------
 lib/hanami/action/mime.rb           | 14 +++++---------
 2 files changed, 15 insertions(+), 23 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index e6735937..6fbb0f1c 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -263,20 +263,6 @@ def media_type_for(format)
           mapping[format]&.media_type
         end
 
-        # @see #media_type_for
-        # @since 2.0.0
-        # @api public
-        alias_method :mime_type_for, :media_type_for
-
-        # @see #media_type_for
-        # @since 2.0.0
-        # @api public
-        def mime_types_for(format)
-          # TODO: deprecate?
-          # FIXME: NOT ANY MORE
-          [media_type_for(format)]
-        end
-
         # @api private
         def accept_types_for(format)
           mapping[format]&.accept_types || []
@@ -286,6 +272,16 @@ def accept_types_for(format)
         def content_types_for(format)
           mapping[format]&.content_types || []
         end
+
+        # @see #media_type_for
+        # @since 2.0.0
+        # @api public
+        alias_method :mime_type_for, :media_type_for
+
+        # @see #media_type_for
+        # @since 2.0.0
+        # @api public
+        alias_method :mime_types_for, :accept_types_for
       end
     end
   end
diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index bbe98455..0f541926 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -372,17 +372,13 @@ def restrictive_response_content_type(request, config)
         end
 
         # @api private
-        # TODO: maybe delete these
         def format_to_media_type(format, config)
-          config.formats.media_type_for(format) ||
-            FORMATS.fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }.media_type
-        end
+          configured_type = config.formats.media_type_for(format)
+          return configured_type if configured_type
 
-        # @api private
-        def format_to_media_types(format, config)
-          config.formats.media_types_for(format).tap { |types| # WIP
-            types << FORMATS[format].media_type if FORMATS.key?(format)
-          }
+          FORMATS
+            .fetch(format) { raise Hanami::Action::UnknownFormatError.new(format) }
+            .media_type
         end
       end
     end

From 364be3a16b5d52a2070893c24909b0b0f188360e Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 13:20:16 +1100
Subject: [PATCH 21/26] Fix a couple of old-style format configs

---
 spec/support/fixtures.rb | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/spec/support/fixtures.rb b/spec/support/fixtures.rb
index f28354f4..4c1ee37c 100644
--- a/spec/support/fixtures.rb
+++ b/spec/support/fixtures.rb
@@ -1631,7 +1631,7 @@ def handle(_req, res)
   end
 
   class Strict < Hanami::Action
-    format :json
+    config.formats.accept :json
 
     def handle(_req, res)
       res.body = res.format
@@ -1639,7 +1639,7 @@ def handle(_req, res)
   end
 
   class Relaxed < Hanami::Action
-    format :all
+    config.formats.accept :all
 
     def handle(_req, res)
       res.body = res.format

From edad4f8c45b63441cd9979c3c7b28df8e369636c Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 13:38:49 +1100
Subject: [PATCH 22/26] Get formats unit spec passing again

---
 lib/hanami/action/config/formats.rb           |  2 +-
 .../unit/hanami/action/config/formats_spec.rb | 22 +++++++++++++------
 2 files changed, 16 insertions(+), 8 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 6fbb0f1c..1b69f009 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -182,7 +182,7 @@ def add(format, mime_types)
           # The old behaviour would have subsequent mime types _replacing_ previous ones
           mapping.reject! { |_, format| format.media_type == mime_type }
 
-          register(format, media_type: Array(mime_types).first)
+          register(format, Array(mime_types).first, accept_types: mime_types)
 
           accept(format) unless @accepted.include?(format)
 
diff --git a/spec/unit/hanami/action/config/formats_spec.rb b/spec/unit/hanami/action/config/formats_spec.rb
index e5ae5559..c052679e 100644
--- a/spec/unit/hanami/action/config/formats_spec.rb
+++ b/spec/unit/hanami/action/config/formats_spec.rb
@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
-RSpec.xdescribe Hanami::Action::Config::Formats do
+RSpec.describe Hanami::Action::Config::Formats do
   subject(:formats) { described_class.new }
 
   describe "#register" do
     it "registers a mapping" do
-      expect { formats.register(:custom, media_type: "application/custom") }
+      expect { formats.register(:custom, "application/custom") }
         .to change { formats.mapping }
         .to include(custom: have_attributes(media_type: "application/custom"))
     end
@@ -14,7 +14,8 @@
       expect {
         formats.register(
           :jsonapi,
-          media_type: "application/vnd.api+json",
+          "application/vnd.api+json",
+          accept_types: ["application/vnd.api+json", "application/json"],
           content_types: ["application/vnd.api+json", "application/json"]
         )
       }
@@ -22,6 +23,7 @@
         .to include(
           jsonapi: have_attributes(
             media_type: "application/vnd.api+json",
+            accept_types: ["application/vnd.api+json", "application/json"],
             content_types: ["application/vnd.api+json", "application/json"]
           )
         )
@@ -108,7 +110,7 @@
 
   describe "#format_for" do
     before do
-      formats.register(:html, media_type: "text/html")
+      formats.register(:html, "text/html")
     end
 
     it "returns the configured format for the given MIME type" do
@@ -116,7 +118,7 @@
     end
 
     it "returns the most recently configured format for a given MIME type" do
-      formats.register :htm, media_type: "text/html"
+      formats.register :htm, "text/html"
 
       expect(formats.format_for("text/html")).to eq(:htm)
     end
@@ -128,7 +130,7 @@
 
   describe "#media_type_for" do
     before do
-      formats.register(:custom, media_type: "application/custom")
+      formats.register(:custom, "application/custom")
     end
 
     it "returns the configured media type for the given format" do
@@ -148,8 +150,14 @@
           .to include(custom: have_attributes(media_type: "application/custom"))
       end
 
+      it "can add a mapping to multiple content types" do
+        expect { formats.add(:json, ["application/json", "application/json+scim"]) }
+          .to change { formats.mapping }
+          .to include(json: have_attributes(media_type: "application/json", accept_types: ["application/json", "application/json+scim"]))
+      end
+
       it "replaces a previously set mapping for a given MIME type" do
-        formats.register(:html, media_type: "text/html")
+        formats.register(:html, "text/html")
         formats.add :custom, "text/html"
 
         expect(formats.mapping).to match(custom: have_attributes(media_type: "text/html"))

From cb5032fb68109dcfb2a63044b3a3d5531a83cf88 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 14:05:54 +1100
Subject: [PATCH 23/26] Update docs

---
 lib/hanami/action/config/formats.rb | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/lib/hanami/action/config/formats.rb b/lib/hanami/action/config/formats.rb
index 1b69f009..f8c4d75a 100644
--- a/lib/hanami/action/config/formats.rb
+++ b/lib/hanami/action/config/formats.rb
@@ -111,13 +111,16 @@ def default=(format)
         #
         # @param format [Symbol] the format name
         # @param media_type [String] the format's media type
-        # @param content_types [Array<String>] the acceptable content types for the format
+        # @param accept_types [Array<String>] media types to accept in request `Accept` headers
+        # @param content_types [Array<String>] media types to accept in request `Content-Type` headers
         #
         # @example
         #   config.formats.register(:scim, media_type: "application/json+scim")
+        #
         #   config.formats.register(
         #     :jsonapi,
-        #     media_type: "application/vnd.api+json",
+        #     "application/vnd.api+json",
+        #     accept_types: ["application/vnd.api+json", "application/json"],
         #     content_types: ["application/vnd.api+json", "application/json"]
         #   )
         #

From 61f4a7861d67eefc43e28798ef15868473aa6348 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 14:11:17 +1100
Subject: [PATCH 24/26] Remove stale TODO

---
 lib/hanami/action/config.rb | 1 -
 1 file changed, 1 deletion(-)

diff --git a/lib/hanami/action/config.rb b/lib/hanami/action/config.rb
index 152e7f8a..67fde299 100644
--- a/lib/hanami/action/config.rb
+++ b/lib/hanami/action/config.rb
@@ -95,7 +95,6 @@ def format(*formats)
         if formats.empty?
           self.formats.values
         else
-          # TODO: add deprecation notice; use config.formats.accept instead
           self.formats.values = formats
           self.formats.default = formats.first
         end

From 73e499a03c24e97e80d858210be6f183fbb2a0b7 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 14:12:14 +1100
Subject: [PATCH 25/26] Add missing private_constant

---
 lib/hanami/action/mime.rb | 1 +
 1 file changed, 1 insertion(+)

diff --git a/lib/hanami/action/mime.rb b/lib/hanami/action/mime.rb
index 0f541926..9e9ce39b 100644
--- a/lib/hanami/action/mime.rb
+++ b/lib/hanami/action/mime.rb
@@ -98,6 +98,7 @@ def initialize(name:, media_type:, accept_types: [media_type], content_types: [m
           )
         )
         .freeze
+      private_constant :FORMATS
 
       # @api private
       MEDIA_TYPES_TO_FORMATS = FORMATS.each_with_object({}) { |(_name, format), hsh|

From 0535c431f375dbe8e673a390622536dbcb725c11 Mon Sep 17 00:00:00 2001
From: Tim Riley <tim@riley.id.au>
Date: Fri, 17 Oct 2025 14:18:14 +1100
Subject: [PATCH 26/26] Add test for restrictive content type setting

---
 spec/integration/hanami/controller/mime_type_spec.rb | 6 ++++++
 spec/support/fixtures.rb                             | 5 +----
 2 files changed, 7 insertions(+), 4 deletions(-)

diff --git a/spec/integration/hanami/controller/mime_type_spec.rb b/spec/integration/hanami/controller/mime_type_spec.rb
index 9d0ef213..283d6d22 100644
--- a/spec/integration/hanami/controller/mime_type_spec.rb
+++ b/spec/integration/hanami/controller/mime_type_spec.rb
@@ -81,6 +81,12 @@
         expect(response.body).to                    eq("custom")
       end
 
+      it %(sets the "Content-Type" header to the format's canonical media type) do
+        response = app.get("/custom_from_accept", "HTTP_ACCEPT" => "application/custom+variant")
+        expect(response.headers["Content-Type"]).to eq("application/custom; charset=utf-8")
+        expect(response.body).to                    eq("custom")
+      end
+
       it 'sets "Content-Type" header according to weighted value' do
         response = app.get("/custom_from_accept", "HTTP_ACCEPT" => "application/custom;q=0.9,application/json;q=0.5")
         expect(response.headers["Content-Type"]).to eq("application/custom; charset=utf-8")
diff --git a/spec/support/fixtures.rb b/spec/support/fixtures.rb
index 4c1ee37c..8cd3571d 100644
--- a/spec/support/fixtures.rb
+++ b/spec/support/fixtures.rb
@@ -1597,7 +1597,7 @@ def handle(req, res)
   end
 
   class CustomFromAccept < Hanami::Action
-    config.formats.register :custom, "application/custom"
+    config.formats.register :custom, "application/custom", accept_types: ["application/custom", "application/custom+variant"]
     config.formats.accept :json, :custom
 
     def handle(*, res)
@@ -1606,9 +1606,6 @@ def handle(*, res)
   end
 
   class UploadAction < Hanami::Action
-    config.formats.register :multipart, "multipart/form-data"
-    config.formats.accept :multipart
-
     def handle(req, res)
       res.format = :txt
       res.body = req.content_type