From a6b68cc3d62db07c12a478d2d351b9805aa968a4 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Fri, 23 Jan 2026 09:00:47 +0200
Subject: [PATCH 1/2] doc: document nuances of
 reitit.coercion/default-parameter-coercion

for #753
---
 doc/ring/coercion.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/doc/ring/coercion.md b/doc/ring/coercion.md
index 48c2debe..a9fdc26e 100644
--- a/doc/ring/coercion.md
+++ b/doc/ring/coercion.md
@@ -63,8 +63,6 @@ Handlers can access the coerced parameters via the `:parameters` key in the requ
                 {:status 200
                  :body {:total total}}))})
 ```
-
-
 ### Nested parameter definitions
 
 Parameters are accumulated recursively along the route tree, just like
@@ -94,6 +92,26 @@ handling for merging eg. malli `:map` schemas.
 ;         [:task-id :int]]}
 ```
 
+### Differences in behaviour for different parameters
+
+All parameter coercions *except* `:body`:
+
+1. Allow keys outside the schema (by opening up the schema using eg. `malli.util/open-schema`)
+2. Keywordize the keys (ie. header & query parameter names) of the input before coercing
+
+In contrast, the `:body` coercion:
+
+1. Uses the specified schema
+   * depending on the coercion, it can be configured as open or closed, see specific coercion docs for details
+2. Does not keywordize the keys of the input before coercion
+   * however, coercions like malli do the keywordization in the coercion stage anyway
+
+This admittedly confusing behaviour is retained currently due to
+backwards compatibility reasons. It can be configured by passing
+option `:reitit.coercion/parameter-coercion` to `reitit.ring/router`
+or `reitit.coercion/compile-request-coercers`. See also:
+`reitit.coercion/default-parameter-coercion`.
+
 ## Coercion Middleware
 
 Defining a coercion for a route data doesn't do anything, as it's just data. We have to attach some code to apply the actual coercion. We can use the middleware from `reitit.ring.coercion`:

From e6e1bfd5c4d4f22b1e10d29fd5bf2f939f92a002 Mon Sep 17 00:00:00 2001
From: Joel Kaasinen <joel.kaasinen@metosin.fi>
Date: Fri, 23 Jan 2026 14:25:19 +0200
Subject: [PATCH 2/2] doc: clarify malli body coercion doc

---
 doc/ring/coercion.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/ring/coercion.md b/doc/ring/coercion.md
index a9fdc26e..2020ca2f 100644
--- a/doc/ring/coercion.md
+++ b/doc/ring/coercion.md
@@ -104,7 +104,7 @@ In contrast, the `:body` coercion:
 1. Uses the specified schema
    * depending on the coercion, it can be configured as open or closed, see specific coercion docs for details
 2. Does not keywordize the keys of the input before coercion
-   * however, coercions like malli do the keywordization in the coercion stage anyway
+   * however, coercions like malli might do the keywordization when coercing json bodies, depending on configuration
 
 This admittedly confusing behaviour is retained currently due to
 backwards compatibility reasons. It can be configured by passing