permittable 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d9b826995301bd0dc72ab69a6560ddfe58e13ae67323a252a9a506c21f61420d
-  data.tar.gz: 5e354c9e104237d9116591df08d4c1a58962f98d543d0f5ff6de983b96f3bc51
+  metadata.gz: ddca88b2da7672d0995e338ab901188c4ba019f4d5928d7aaf0a5f73a7f8ba9c
+  data.tar.gz: 1a66ef88adc7ab843798f25c7a5e3444a3e550795d1353139d52b65e05ac5005
 SHA512:
-  metadata.gz: c9cf62a2210a42cad9190f25ce259250c268dabf72bb966bae4110d2c627f27ce7a050a64f92c9e1729c9eb088d48077384b901481475a5cae077d1d802684ab
-  data.tar.gz: a6db0156d761c972ef0c9f6b41ef96e3fee3f0f48158ce01344b8a6ea39f9a8504dd2df015bcf3c379841420a66e857a42a2d0ff07d2d94902b49d89fec6b570
+  metadata.gz: 7288c663fd8a2d740ca1c1e7fe9ad61d50854fa47e0e9c4a75bb0922bd119d7c4ca9fe99b020b6ea03edfb456d0fe88322161d53cc1bdd71afb6b88f6cf6ccda
+  data.tar.gz: a9ecd5c620fac068991a0401d76f339163eb20b6bed73ab83a33f5c3895f8bfb82479a86ab9d6385d85321732ce8ebc6c332819b32174bc8d0494c6021d1623f

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 <!-- CHANGELOG.md -->
 
+## 0.6.0 (2026-09-08)
+<!-- title: nullable fields, :json, and strict dates -->
+
+Two gaps in the field vocabulary closed and one guess removed. A contract can now say *clear this column* (`nullable:`) and *this hash has no shape, but it has bounds* (`:json`), and a date string must name the whole date instead of borrowing the missing parts from today. Contracts that use neither new option see only the date-parsing change, which is called out below.
+
+### Added
+- **`:json` field type — free-form hashes, the `jsonb` column case.** A `json`/`jsonb` column exists precisely so its contents need no schema, and every other field kind describes a shape. Until now a contract had only bad options for one: declare sub-keys you don't know, or leave the key undeclared — in which case the contract **silently dropped it** and the column never saw the data. Strong parameters has always had an answer (`params.permit(metadata: {})`); now so does a contract. `optional :metadata, :json` passes an arbitrary Hash through untouched — keys neither filtered nor cast, nested arrays and mixed scalars intact, `unknown:` deliberately not descending into it, `{}` a value rather than an absence, anything that is not a Hash an `invalid_type`. What it gives up is the shape; what it keeps is every bound worth having: **`length:`** caps the top-level key count, **`max_depth:`** caps container nesting with arrays counting as a level (violation code `depth`), `validate:`/`transform:` see the whole hash, and the field maps onto a column like a scalar does, so the schema-drift guard still catches a dropped `metadata` column. That matters more than it looks — an unbounded `jsonb` column is where clients put megabytes and 200-level-deep objects, and "opaque, but not unlimited" is strictly more than `permit(metadata: {})` can say. Values arrive as plain data, never `ActionController::Parameters`, so assigning straight to a `jsonb` attribute is safe. Exported as `{"type": "object"}` with `minProperties`/`maxProperties`, plus `x-permittable-max-depth` for the nesting bound JSON Schema has no keyword for.
+- **`permittable:generate` now drafts `json`, `jsonb` and `hstore` columns as `:json`** instead of leaving a TODO comment. Columns with no faithful representation at all (`binary`, geometry types) still become TODOs rather than guesses.
+
+- **`nullable:` field option — an explicit null is now part of a contract's vocabulary.** One absence rule (`nil` and `""` are both absent) is right for `PATCH` and wrong for the request that means *clear this*; `nullable: true` splits it in two for a single field. A key the client never sent stays **absent** — `default:` applies to it, a `required` field still violates `missing` — but a key sent **empty** (JSON `null`, or `""` from a form) is an explicit null and yields `nil` in the result, **ahead of the field's `default:`**, which is exactly what a `PATCH` clearing a column needs. Nothing is cast or checked for an explicit null: `in:`, `format:`, `length:`, `validate:`, and `transform:` never see a `nil` they didn't agree to handle. `required` + `nullable` reads as it does in SQL (the client must state the field; `null` is a legal statement), `default: nil` — legal only on a nullable field — gives the `PUT` reading where absence also means clear, and on arrays and nested blocks `nullable:` applies to the array or object itself, never its contents (a null *element* is still `invalid_type`). Exported JSON Schema / OpenAPI stays truthful: the field's `type` gains `"null"`, and a nullable `in:` set lists `null` in its `enum` (the one keyword that constrains the instance rather than a type). The RSpec matcher gains a `.nullable` chain, and `default: nil` / `example: nil` on a non-nullable field now fails at class load naming the fix, instead of the confusing `invalid_type`.
+
+Contracts that don't opt in are byte-for-byte unaffected: absence keeps its single meaning and nothing new appears in an exported schema.
+
+### Fixed
+- **`:date` and `:datetime` invented the parts a string left out, from today's date.** Coercion is documented as strict — "a value the type cannot faithfully represent is a violation, not a guess" — but it handed strings straight to `Date.parse`, which fills in what they omit from the current date: `"09/2026"` became the 1st of September, `"5th"` became the 5th of *this* month of *this* year, `"Sept"` became the 1st of September *this* year. The same request therefore meant different things on different days, which is a guess and a non-deterministic one. A `:date` or `:datetime` string must now name all three of year, month and day; which **format** it names them in is still `Date.parse`'s business, so every complete format it understands keeps working (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`, `"5 September 2026"`). A `:datetime` may still omit the **time** part, which reads as midnight UTC as documented, but a string with only a time (`"10:30"`, previously *today* at 10:30) is now `invalid_type`. `Date`, `Time`, `DateTime` and `ActiveSupport::TimeWithZone` objects are unaffected.
+
+  This is a **behaviour change** for any endpoint that was relying on the fill-in, but the values it produced were not the ones the client meant, and an exported `"format": "date"` already promised RFC 3339 rather than `"5th"`.
+
+## 0.5.2 (2026-09-06)
+<!-- title: Railtie coverage and a new README -->
+
+Patch release with no behaviour changes: the boot-time integration gets its first real spec, and the README was rewritten from the ground up.
+
+### Added
+- **`spec/railtie_spec.rb` — the boot-time integration is now covered.** Everything `Permittable::Railtie` does happens during a Rails boot, and none of it had a spec: the `filter_parameters` wiring, its reach into ActiveRecord, or the rake tasks. Unit specs cannot see any of it, and the `FakeController` harness deliberately has no Rails at all. The new spec boots a **real Rails application in a subprocess** — the same approach the "without Rails loaded" specs use, and for the same reason: a boot mutates global state (`Rails.application` is a singleton, initializers run once) and must not leak into the rest of the suite. It asserts that exactly one filter proc is appended without disturbing the app's own entries, that a `sensitive:` field declared by a controller loaded **after** boot is redacted (the whole reason for a live registry rather than appended symbols), that the proc reaches `ActiveRecord::Base.filter_attributes` so a model's `#inspect` redacts too, and that both rake tasks load. `railties` joins the dev bundle for it, and the spec skips rather than fails where railties is absent, so a host without Rails — and the compatibility gemfiles that omit it — are unaffected.
+
+### Changed
+- **README rewritten as a navigable overview.** A badges-and-nav header, a table of contents, and sections grouped into Guide, Adopting on a live API, Beyond the controller, and Reference; a motivating before/after example; a diagram of how one contract feeds validation, the drift guard, OpenAPI export, and the RSpec matchers; and the long enumerations (class-load errors, the schema mapping table) folded into `<details>` blocks. Documentation only.
+
 ## 0.5.1 (2026-09-02)
 <!-- title: nested input outside Rails -->
 

data/README.md

@@ -1,14 +1,30 @@
-# Permittable
+<h1 align="center">Permittable</h1>
+
+<p align="center"><strong>Strong parameters for Rails that also know types, bounds, and defaults.</strong></p>
+
+<p align="center">
+  <a href="https://rubygems.org/gems/permittable"><img src="https://img.shields.io/gem/v/permittable.svg" alt="Gem Version"></a>
+  <a href="https://github.com/VSN2015/permittable/actions/workflows/ci.yml"><img src="https://github.com/VSN2015/permittable/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.ruby-lang.org/"><img src="https://img.shields.io/badge/ruby-%E2%89%A5%203.2-CC342D.svg" alt="Ruby >= 3.2"></a>
+  <a href="https://rubyonrails.org/"><img src="https://img.shields.io/badge/rails-5.0%20%E2%80%93%208.x-D30001.svg" alt="Rails 5.0 - 8.x"></a>
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#guide">Guide</a> ·
+  <a href="#adopting-on-a-live-api">Adopting on a live API</a> ·
+  <a href="#beyond-the-controller">Beyond the controller</a> ·
+  <a href="#reference">Reference</a> ·
+  <a href="docs/comparison.md">Comparison</a> ·
+  <a href="CHANGELOG.md">Changelog</a>
+</p>
 
-[![Gem Version](https://img.shields.io/gem/v/permittable.svg)](https://rubygems.org/gems/permittable)
-[![CI](https://github.com/VSN2015/permittable/actions/workflows/ci.yml/badge.svg)](https://github.com/VSN2015/permittable/actions/workflows/ci.yml)
-[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
-
-**Strong parameters for Rails that also know types, bounds, and defaults.**
+---
 
 `params.permit` answers exactly one question: *which keys may pass?* Everything else — is `age` really a number, is `email` shaped like an email, what should `plan` be when the client omits it, and *why* was this request rejected — is left to you, usually as hand-written checks scattered through the action.
 
-A Permittable contract answers those questions too. It **casts** each field to a declared type, **validates** it, applies **defaults**, optionally **reshapes** the output, and turns every failure into a machine-readable 422 that names the offending parameter.
+A Permittable **contract** answers those questions too. Declared once on the controller class, it **casts** each field to a declared type, **validates** it, applies **defaults**, optionally **reshapes** the output, and turns every failure into a machine-readable 422 that names the offending parameter.
 
 And because a contract is *class-level data* rather than code inside the action, it can be inspected — and checked against your database when the controller loads, so a column dropped by a migration fails the deploy instead of the request.
 
@@ -44,26 +60,33 @@ A violating request never reaches your action:
              "details": [{ "param": "user.age", "code": "inclusion" }] } }
 ```
 
----
+## Why
 
-## Contents
+Here is what the contract above replaces. Every Rails codebase has a version of this, and no two of them agree on the error shape:
 
-- [Why](#why) · [Installation](#installation) · [How a request flows](#how-a-request-flows)
-- [Declaring a contract](#declaring-a-contract) · [The field DSL](#the-field-dsl) · [Field options](#field-options)
-- [Types and strict coercion](#types-and-strict-coercion) · [Absence, defaults, and partial updates](#absence-defaults-and-partial-updates)
-- [Violations and error responses](#violations-and-error-responses) · [Custom error messages](#custom-error-messages-message) · [Unknown parameters](#unknown-parameters)
-- [Output reshaping](#output-reshaping-transform-and-finalize) · [The schema-drift guard](#the-schema-drift-guard)
-- [Sensitive parameters](#sensitive-parameters-and-log-redaction) · [Instrumentation](#instrumentation)
-- [Monitor mode](#monitor-mode-roll-out-without-rejecting) · [Generating draft contracts](#generating-draft-contracts-permittablegenerate) · [Testing contracts](#testing-contracts-rspec-matchers)
-- [Standalone contracts](#standalone-contracts-no-controller) · [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
-- [API reference](#api-reference) · [Errors caught at class load](#errors-caught-at-class-load) · [Compatibility](#compatibility)
+```ruby
+def create
+  attrs = params.require(:user).permit(:name, :email, :age, :plan)
+
+  if attrs[:age].present?
+    age = Integer(attrs[:age], exception: false)
+    return render(json: { error: "age must be a number" }, status: 422) if age.nil?
+    return render(json: { error: "age must be 18..120" },  status: 422) unless (18..120).cover?(age)
+    attrs[:age] = age
+  end
+  unless attrs[:email].to_s.match?(URI::MailTo::EMAIL_REGEXP)
+    return render(json: { error: "email is invalid" }, status: 422)
+  end
+  attrs[:plan] = "free" if attrs[:plan].blank?
 
----
+  User.create!(attrs)
+end
+```
 
-## Why
+A contract moves all of it out of the action and into data that the rest of your toolchain can read:
 
 | | `params.permit` | `params.expect` (Rails 8) | Permittable |
-|---|---|---|---|
+|---|:---:|:---:|:---:|
 | Filters unknown keys | ✅ | ✅ | ✅ |
 | Requires a root key | via `require` | ✅ | ✅ |
 | Casts to a declared type | ❌ | ❌ | ✅ |
@@ -75,18 +98,50 @@ A violating request never reaches your action:
 | Exports OpenAPI / JSON Schema | ❌ | ❌ | ✅ |
 | Report-only rollout mode | ❌ | ❌ | ✅ |
 | Drafts contracts from your schema | ❌ | ❌ | ✅ |
+| Works outside controllers | ❌ | ❌ | ✅ |
 
-The design rests on one idea: **a contract is data, not code.** It is declared once at the class level, frozen, inheritable, and introspectable. Everything else here follows from that — the drift guard can read it at boot, `finalize` can run on a bare object with no controller state, and the whole contract can be printed or tested without a request.
+Every option in this space is good software, and Permittable is not always the right one. A longer, honest comparison — `params.expect`, rails_param, dry-validation, typed_params, rswag, the cases where each is the better choice, benchmarks, and migration costs — lives in [docs/comparison.md](docs/comparison.md).
 
-A longer, honest comparison — `params.expect`, rails_param, dry-validation, typed_params, rswag, with the cases where each of them is the better choice, plus benchmarks and migration costs — lives in [docs/comparison.md](docs/comparison.md).
+## One idea: a contract is data
 
-## Installation
+Everything in this gem follows from a single decision. A contract is **declared once at the class level, frozen, inheritable, and introspectable**. It is not code that runs inside your action. That makes it readable by more than the validator:
+
+```
+                  ┌────────────────────────────────────────────────────┐
+                  │  permit_params :create, root: :user, model: User   │
+                  │    required :email, :string, format: EMAIL_REGEXP  │
+                  │    optional :age,   :integer, in: 18..120          │
+                  │  end                                               │
+                  └──────────────────────────┬─────────────────────────┘
+                             one frozen, class-level contract
+                                             │
+         ┌─────────────────┬─────────────────┼─────────────────┬─────────────────┐
+         ▼                 ▼                 ▼                 ▼                 ▼
+   Validator         Drift guard       OpenAPI           RSpec matchers    Contract
+   casts, checks,    compares fields   3.1 export from   assert on the     the same DSL on
+   defaults; a 422   to DB columns     the same data     rule itself, no   any Hash, no
+   names the         at class load;    the server        request needed    controller
+   parameter         fails the deploy  enforces                            required
+```
+
+The principles that fall out of it:
+
+- **Strict, never lenient.** `"abc"` is never `0`. A value the type cannot faithfully represent is a violation, not a guess.
+- **`nil` and `""` are absent.** Absent optionals are omitted from the result, so partial updates never nil-out columns.
+- **Mistakes fail at class load.** A malformed contract, a default that violates its own field, or a column that no longer exists fails the boot, never the request.
+- **The request's `params` is never mutated.** Reshaping happens on the validated copy.
+- **Exports never guess.** Anything JSON Schema cannot represent stays visible as an `x-permittable-*` extension instead of being mistranslated.
+- **One dependency.** `activesupport` is the only runtime requirement. Rails, ActionPack, and ActiveRecord are optional integration points.
+
+## Quick start
+
+**1. Add the gem**
 
 ```ruby
 gem "permittable"
 ```
 
-Then include it wherever you need it — typically once in `ApplicationController`:
+**2. Include it once**
 
 ```ruby
 class ApplicationController < ActionController::Base
@@ -94,28 +149,79 @@ class ApplicationController < ActionController::Base
 end
 ```
 
-The **only runtime dependency is `activesupport`**. `actionpack` (for `rescue_from`, `before_action`, and `ActionController::Parameters`) and `activerecord` (for the `model:` schema-drift guard) are optional — every touchpoint is guarded with `respond_to?`/`defined?`, so your app brings whatever it already has. The concern works on a plain Ruby object that responds to `params`, which is what makes it straightforward to unit-test.
+**3. Declare a contract and read `permitted_params`**
+
+```ruby
+class OrdersController < ApplicationController
+  permit_params :create, root: :order, model: Order do
+    required :sku,      :string
+    optional :quantity, :integer, in: 1..99, default: 1
+    optional :notes,    :string,  length: 0..500
+  end
+
+  def create
+    Order.create!(permitted_params)
+  end
+end
+```
+
+That is the whole integration. Violations render the 422 envelope automatically, `model: Order` verifies the fields against the `orders` table when the class loads, and every rejected request emits an `invalid_parameters.permittable` notification.
+
+Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live API](#adopting-on-a-live-api): the gem can draft the contracts for you, and run them in a report-only mode until you are ready to enforce.
 
 > **Naming note:** some legacy stacks (InheritedResources) define their own `permitted_params`. Don't include both on one controller.
 
-## How a request flows
+## Contents
+
+- **[Guide](#guide)**
+  - [How a request flows](#how-a-request-flows)
+  - [Declaring a contract](#declaring-a-contract)
+  - [The field DSL](#the-field-dsl)
+  - [Field options](#field-options)
+  - [Types and strict coercion](#types-and-strict-coercion)
+  - [Free-form hashes](#free-form-hashes-json)
+  - [Absence, defaults, and partial updates](#absence-defaults-and-partial-updates)
+  - [Explicit nulls](#explicit-nulls-nullable)
+  - [Violations and error responses](#violations-and-error-responses)
+  - [Custom error messages](#custom-error-messages-message) · [Localizing with I18n](#localizing-default-messages-i18n)
+  - [Unknown parameters](#unknown-parameters)
+  - [Output reshaping](#output-reshaping-transform-and-finalize)
+  - [The schema-drift guard](#the-schema-drift-guard)
+  - [Sensitive parameters and log redaction](#sensitive-parameters-and-log-redaction)
+  - [Instrumentation](#instrumentation)
+- **[Adopting on a live API](#adopting-on-a-live-api)**
+  - [Monitor mode](#monitor-mode-roll-out-without-rejecting)
+  - [Generating draft contracts](#generating-draft-contracts-permittablegenerate)
+- **[Beyond the controller](#beyond-the-controller)**
+  - [Testing contracts](#testing-contracts-rspec-matchers)
+  - [Standalone contracts](#standalone-contracts-no-controller)
+  - [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
+- **[Reference](#reference)**
+  - [API](#api) · [Errors caught at class load](#errors-caught-at-class-load) · [Compatibility](#compatibility)
+- [Development](#development) · [License](#license)
+
+---
+
+## Guide
+
+### How a request flows
 
 ```
-params
-  │
-  ├─ 1. unwrap root:          params[:user]        → 400 if missing or not a hash
-  ├─ 2. per field:  normalize → cast → validate → transform
-  ├─ 3. unknown-key check     at every nesting level
-  ├─ 4. finalize              only if nothing violated
-  │
-  └─ permitted_params → HashWithIndifferentAccess     (or raises InvalidParameters)
+request params
+   │
+   ├─ 1  unwrap root:        params[:user]                missing or not a hash → 400
+   ├─ 2  each field          normalize → cast → validate → transform
+   ├─ 3  unknown-key check   at every nesting level       (unknown: :ignore | :log | :error)
+   ├─ 4  finalize            only when nothing violated
+   │
+   └─ permitted_params  →  HashWithIndifferentAccess      or raises InvalidParameters → 422
 ```
 
 Validation is **lazy by default**: it runs on the first `permitted_params` call, so an action that never reads params never pays for it. Pass `enforce: true` to run it in a `before_action` instead, rejecting bad requests before the action body executes. Results are **memoized per action**.
 
 In [monitor mode](#monitor-mode-roll-out-without-rejecting) the same flow runs, but a violation is reported instead of raised and the request proceeds with the raw params passed through.
 
-## Declaring a contract
+### Declaring a contract
 
 ```ruby
 permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, mode: nil, desc: nil, &contract)
@@ -147,39 +253,35 @@ end
 
 Rules accumulate by **reassignment, never mutation**, so subclasses inherit copy-on-write and can never corrupt a parent's contract.
 
-## The field DSL
+### The field DSL
 
-### Scalars
+Three verbs. `required` and `optional` declare scalars (or, with a block, nested hashes); `array` declares a list.
 
 ```ruby
-required :name, :string          # type defaults to :string
+# Scalars — the type defaults to :string
+required :name, :string
 optional :age,  :integer
-```
 
-### Nested hashes
-
-Pass a block instead of a type. Violation paths are dotted (`user.address.zip`).
-
-```ruby
+# Nested hashes — pass a block instead of a type. Violation paths are dotted: user.address.zip
 optional :address do
   required :city, :string
   optional :zip,  :string, format: /\A\d{5}\z/
 end
-```
-
-### Arrays
 
-`of:` declares an array of scalars; a block declares an array of hashes. Arrays are **optional unless `required: true`**, `length:` constrains the element **count**, and element failures carry their index (`items[1]`).
-
-```ruby
-array :tag_names, of: :string, length: 0..10
+# Arrays — of: for scalars, a block for hashes. Element failures carry their index: items[1].sku
+array :tag_names,  of: :string, length: 0..10
 array :line_items, required: true do
   required :sku,      :string
   required :quantity, :integer, in: 1..99
 end
+
+# Free-form hashes — :json takes any hash, uncast and unfiltered, with bounds
+optional :metadata, :json, max_depth: 3, length: 0..32
 ```
 
-## Field options
+Arrays are **optional unless `required: true`**, and `length:` on an array constrains the element **count**.
+
+### Field options
 
 Which options are legal depends on the field kind — anything else raises at class load.
 
@@ -196,9 +298,11 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `sensitive:` | ✅ | ✅ | ✅ | Register the field name for [log redaction](#sensitive-parameters-and-log-redaction) |
 | `message:` | ✅ | ✅ | ✅ | Human-readable copy for violations on this field — a String, or a Hash of code → String. See [custom messages](#custom-error-messages-message) |
 | `of:` | — | ✅ | — | Element type for an array of scalars (default `:string`) |
+| `max_depth:` | — | — | — | `:json` fields only — maximum container nesting. See [free-form hashes](#free-form-hashes-json) |
 | `required:` | — | ✅ | — | Arrays are optional unless this is `true` |
 | `desc:` | ✅ | ✅ | ✅ | Documentation only — the field's `description` in [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) |
 | `example:` | ✅ | ✅ | — | Documentation only, but **validated against the field's own contract at class load**, like `default:` |
+| `nullable:` | ✅ | ✅ | ✅ | An explicitly-sent empty value yields `nil` instead of counting as absent — see [explicit nulls](#explicit-nulls-nullable) |
 
 ¹ `format:`, `length:`, and `normalize:` reason about characters and are **only valid on `:string` fields**. On any other type they would silently apply to an already-cast value, so declaring them raises at class load.
 
@@ -208,7 +312,7 @@ Which options are legal depends on the field kind — anything else raises at cl
 optional :slug, :string, validate: ->(v) { v.match?(/\A[a-z0-9-]+\z/) || :malformed_slug }
 ```
 
-## Types and strict coercion
+### Types and strict coercion
 
 Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`. Rails' casts are lenient by design — `"abc".to_i` is `0`, `Boolean.cast("abc")` is `true` — and silently corrupting untrusted input is precisely what a contract must not do. A value the type cannot faithfully represent is a **violation, not a guess**.
 
@@ -219,31 +323,94 @@ Coercion is **deliberately strict**, and deliberately *not* `ActiveModel::Type`.
 | `:float` | `Numeric`; any `Float()`-parseable string | `"abc"` |
 | `:decimal` | `Numeric` or `String` → `BigDecimal` | Unparseable strings |
 | `:boolean` | `true`/`false`, `"true"`/`"false"`, `"1"`/`"0"`, `1`/`0` | `"yes"`, `"on"`, `2` |
-| `:date` | `Date`; any `Date.parse`-able string | Unparseable strings |
-| `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`, parseable strings | Unparseable strings |
+| `:date` | `Date`; a string naming a **complete** date, in any format `Date.parse` understands (`"2026-09-05"`, `"2026/09/05"`, `"Sep 5, 2026"`) | Unparseable strings, and **incomplete** ones (`"09/2026"`, `"5th"`, `"Sept"`) |
+| `:datetime` | `Time`, `DateTime`, `ActiveSupport::TimeWithZone`, `Date`; a string naming a complete date, with or without a time | Unparseable strings, and any string without a complete date (`"10:30"`) |
+| `:json` | Any `Hash` — passed through uncast, see [free-form hashes](#free-form-hashes-json) | Arrays, scalars |
+
+**Dates are parsed, never guessed.** `Date.parse` fills in what a string omits *from today* — `"09/2026"` becomes the 1st, `"5th"` becomes this month of this year — so the same request would mean different things on different days. A `:date` or `:datetime` string must therefore name all three of year, month and day; which **format** it names them in is `Date.parse`'s business, so every complete format it understands still works. A `:datetime` may omit the *time* part, which reads as midnight UTC.
 
-Two behaviours worth committing to memory:
+Two more behaviours worth committing to memory:
 
 - **Type confusion is a violation, not a 500.** A request of `?age[]=1` against a scalar `:integer` field yields `invalid_type`. Arrays, hashes, and nested `ActionController::Parameters` can never satisfy a scalar type, so the classic "`NoMethodError` on `[]`" crash is impossible.
 - **Datetimes are normalised to UTC.** A zoneless string parses as UTC regardless of the host timezone, which keeps behaviour deterministic across machines; explicit offsets are honoured and converted.
 
-## Absence, defaults, and partial updates
+### Free-form hashes (`:json`)
+
+A `json`/`jsonb` column exists precisely so its contents need no schema. Every other field kind describes a shape, so until `:json` a contract had only bad options for one: declare sub-keys you don't know, or leave the key undeclared — in which case the contract **silently dropped it**, and the column never saw the data. Strong parameters has always had an answer here (`params.permit(metadata: {})`); now so does a contract.
+
+```ruby
+permit_params :create, root: :user, model: User do
+  required :name,     :string
+  optional :metadata, :json, max_depth: 3, length: 0..32
+end
+```
+
+The hash passes through **untouched** — keys are neither filtered nor cast, nested arrays and mixed scalars survive, and `unknown:` does not descend into it. `{}` is a value, not an absence. Anything that is not a hash (an array, a string, a number) is `invalid_type`.
+
+What you give up is the shape. What you keep:
+
+| | |
+|---|---|
+| `length:` | Caps the **top-level key count** — same reading as an array's element count |
+| `max_depth:` | Caps **container nesting**, counting arrays as a level: `{"a": 1}` is 1, `{"a": {"b": 1}}` and `{"a": [1, 2]}` are 2, `{"a": [{"b": 1}]}` is 3. Violation code `depth` |
+| `validate:` / `transform:` | See the whole hash, so any check you can write in Ruby still applies |
+| `model:` | The field maps onto a column like a scalar does, so the [drift guard](#the-schema-drift-guard) still catches a dropped `metadata` column |
+| `sensitive:` / `nullable:` / `message:` / `desc:` / `default:` / `example:` | Behave as on any other field (`default:`/`example:` must be a hash, and are checked against the field's own bounds at class load) |
+
+Bounding it matters more than it looks: an unbounded `jsonb` column is where clients put megabytes and 200-level-deep objects. `max_depth:` and `length:` are how a contract says "opaque, but not unlimited" — which is strictly more than `permit(metadata: {})` can say.
+
+Values arrive as plain data (`HashWithIndifferentAccess`), never `ActionController::Parameters`, so assigning straight to a `jsonb` attribute is safe.
+
+In [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) the field is `{"type": "object"}` plus `minProperties`/`maxProperties`; JSON Schema has no nesting-depth keyword, so `max_depth:` stays visible as `x-permittable-max-depth` rather than being dropped or mistranslated.
+
+### Absence, defaults, and partial updates
 
 `nil` and `""` are **both treated as absent** — the query-parameter convention, where an untouched form field arrives as an empty string. Boolean `false` is present.
 
 That single rule produces the behaviour you want from a `PATCH`:
 
-- An **absent optional field is omitted** from the result, so partial updates never nil-out columns.
-- An **absent required field violates** with `missing`.
-- An absent field **with a `default:` gets the default** — so a defaulted field can never report `missing`. (Declaring `required:` alongside `default:` is a class-load error, since a default implies optionality.)
+| The field is… | Result |
+|---|---|
+| absent and **optional** | omitted from the result, so partial updates never nil-out columns |
+| absent and **required** | a `missing` violation |
+| absent with a **`default:`** | the default — a defaulted field can never report `missing` |
 
-Because absence and `nil` are the same thing here, **clearing a column to NULL is outside a contract's vocabulary**. Do that explicitly in the action.
+Declaring `required:` alongside `default:` is a class-load error, since a default implies optionality. And because absence and `nil` are the same thing here, a plain field cannot clear a column to NULL — declare it [`nullable:`](#explicit-nulls-nullable) when it should.
 
 Defaults are checked against the field's own contract when the class loads, so `default: "gold"` on a field declared `in: %w[free pro]` fails at boot rather than on every request.
 
-## Violations and error responses
+### Explicit nulls (`nullable:`)
 
-Every failure raises `Permittable::InvalidParameters`, carrying `details` (an array of `{ param:, code: }`, plus a `message:` when the field [declares one](#custom-error-messages-message)) and a `status`. On a real controller it is auto-rescued into the error envelope.
+One rule — `nil` and `""` are absent — is right for `PATCH` and wrong for the request that means *clear this*. `nullable: true` splits it in two for a single field:
+
+```ruby
+permit_params :update, root: :user, model: User do
+  optional :nickname, :string, nullable: true
+  optional :plan,     :string, in: %w[free pro], default: "free", nullable: true
+end
+```
+
+| Request | `nickname` in the result |
+|---|---|
+| `{ "user": {} }` | **omitted** — the column is untouched |
+| `{ "user": { "nickname": null } }` | `nil` — the column is cleared |
+| `{ "user": { "nickname": "" } }` | `nil` — the form-encoded spelling of the same intent |
+
+A key the client never sent is still **absent**: `default:` applies to it and a `required` field still violates with `missing`. Only *present-but-empty* changes meaning, and it changes it decisively — an explicit null wins over the field's `default:`, which is the behaviour a `PATCH` needs (`{ "plan": null }` clears the plan instead of silently resetting it to `"free"`).
+
+Nothing is cast or checked for an explicit null. `in:`, `format:`, `length:`, `validate:`, and `transform:` all see a value or nothing at all — never a `nil` they never agreed to handle.
+
+Three more readings worth knowing:
+
+- **`required` + `nullable`** is coherent, and means what it says in SQL: the client *must* state the field, and `null` is a legal statement. A missing key still violates.
+- **`default: nil`** — legal only on a nullable field — gives the `PUT` reading, where absence *also* means clear.
+- **On arrays and nested blocks**, `nullable:` applies to the array or object itself, never to its contents. `{ "tags": null }` yields `nil` (distinct from `[]`, which still gets length-checked); a null *element* inside `tags` is still `invalid_type`.
+
+Exported [OpenAPI](#exporting-openapi-docs-that-cannot-drift) tells the truth about all of this: a nullable field's `type` gains `"null"`, and a nullable `in:` set lists `null` in its `enum`.
+
+### Violations and error responses
+
+Every failure raises `Permittable::InvalidParameters`, carrying `details` (an array of `{ param:, code: }`, plus a `message:` when the field [declares one](#custom-error-messages-message)) and a `status`. On a real controller it is auto-rescued into the error envelope shown at the [top of this README](#permittable).
 
 | Code | Raised when |
 |---|---|
@@ -258,11 +425,11 @@ Every failure raises `Permittable::InvalidParameters`, carrying `details` (an ar
 
 Paths are fully qualified: `user.address.zip`, `line_items[1].sku`.
 
-**Status codes:** a missing root key renders **400** (the request is malformed — the envelope you asked for isn't there); field-level violations render **422** (well-formed, semantically wrong).
+**Status codes.** A missing root key renders **400** — the request is malformed; the envelope you asked for isn't there. Field-level violations render **422** — well-formed, semantically wrong.
 
-**Custom rendering:** if your controller defines `render_error`, the envelope delegates to it as `render_error(message:, code:, status:, errors:)` — the `errors:` key is passed only when details exist, so hosts documenting a three-keyword contract keep working. Otherwise the inline JSON shape shown at the top of this README is rendered. Either way, `render_invalid_parameters` is a normal method you can override.
+**Custom rendering.** If your controller defines `render_error`, the envelope delegates to it as `render_error(message:, code:, status:, errors:)` — the `errors:` key is passed only when details exist, so hosts documenting a three-keyword contract keep working. Otherwise the inline JSON shape is rendered. Either way, `render_invalid_parameters` is a normal method you can override. For full control over the body (RFC 9457, a different envelope), `error.details` gives you the structured violations to build from.
 
-## Custom error messages (`message:`)
+### Custom error messages (`message:`)
 
 Violations stay machine-first — the `code` is the contract — but any field can attach human-readable copy with `message:`. A **String** covers every code on the field; a **Hash of code → String** targets specific codes, and codes without an entry keep the default rendering:
 
@@ -293,7 +460,7 @@ The rules:
 - `violate!` in `finalize` takes the same idea as a keyword: `violate!("user.ends_at", :before_start, message: "must be after starts_at")`.
 - A `message:` that is neither a String nor a code → String Hash raises at class load, like every other contract mistake.
 
-### Localizing default messages (I18n)
+#### Localizing default messages (I18n)
 
 App-wide copy for a violation code — without repeating `message:` on every field — comes from I18n, under `permittable.errors.<code>`:
 
@@ -310,9 +477,7 @@ en:
 
 Resolution order per violation: the field's own `message:` (String, or the Hash entry for that code) → the app's `permittable.errors.<code>` translation → the bare `{ param:, code: }` shape. The lookup also covers a missing `root:`, `unknown` keys, Symbol codes returned by `validate:` (`permittable.errors.must_be_even`), and `violate!` codes in `finalize` (an explicit `violate!(..., message:)` still wins). Only a String translation counts — a missing key or a nested Hash falls back to the bare shape rather than leaking structure to clients. No I18n, no change: apps without the gem or the keys behave exactly as before.
 
-For full control over the response body itself (RFC 9457, a different envelope), override `render_invalid_parameters` or define `render_error` as described above; `error.details` gives you the structured violations to build from.
-
-## Unknown parameters
+### Unknown parameters
 
 `unknown:` decides what happens to keys you never declared, **at every nesting level**.
 
@@ -324,13 +489,11 @@ For full control over the response body itself (RFC 9457, a different envelope),
 
 Rails merges `controller`, `action`, and `format` into `params`; these are exempt at the top level so `unknown: :error` doesn't flag the router's own bookkeeping. Inside a `root:` or a nested hash there is no such exemption, because nothing legitimately injects keys there.
 
-## Output reshaping (`transform:` and `finalize`)
+### Output reshaping (`transform:` and `finalize`)
 
 This is the safe replacement for params-mutating `before_action`s. **Both layers operate on the validated copy — the request's `params` is never touched.**
 
-### `transform:` — per field
-
-A callable applied **after** cast and validation, reshaping one field's output:
+**`transform:` — per field.** A callable applied **after** cast and validation, reshaping one field's output:
 
 ```ruby
 required :tags, :string, transform: ->(v) { v.split(",") }
@@ -338,11 +501,9 @@ required :tags, :string, transform: ->(v) { v.split(",") }
 
 It runs only on request-supplied values. Absent fields stay absent, `default:` values are authored in their final shape, and a **partially-invalid array is never transformed** — user code is never handed garbage it didn't agree to see.
 
-### `finalize` — per contract
+**`finalize` — per contract.** Declared once, at the top level only. It runs after every field has validated cleanly, receives the result hash, and must return the final `Hash`. Use it to combine parallel fields, build value objects, or drop scaffolding keys.
 
-Declared once, at the top level only. It runs after every field has validated cleanly, receives the result hash, and must return the final `Hash`. Use it to combine parallel fields, build value objects, or drop scaffolding keys.
-
-It executes on a **bare runner, not the controller**, so contracts stay pure data plus pure functions and can never grow a dependency on request state. Its one extra verb is `violate!(param, code, message: nil)`, which records a violation (the optional [`message:`](#custom-error-messages-message) rides into the detail) and **halts the block immediately** — so the code after a `violate!` may assume the invariant it just checked. That makes `finalize` the natural home for cross-field validation (`ends_at` after `starts_at`, matching array lengths).
+It executes on a **bare runner, not the controller**, so contracts stay pure data plus pure functions and can never grow a dependency on request state. Its one extra verb is `violate!(param, code, message: nil)`, which records a violation and **halts the block immediately** — so the code after a `violate!` may assume the invariant it just checked. That makes `finalize` the natural home for cross-field validation (`ends_at` after `starts_at`, matching array lengths).
 
 ```ruby
 permit_params :create, root: :lease_addendum_form do
@@ -364,7 +525,7 @@ end
 
 Forgetting to return the hash raises an `ArgumentError` telling you exactly that.
 
-## The schema-drift guard
+### The schema-drift guard
 
 This is why `model:` exists. Pass a model class (or `true` to infer it from `controller_name`) and **every non-virtual scalar field is checked against the model's columns when the macro runs** — that is, at controller class load.
 
@@ -384,7 +545,7 @@ The error carries a ready-to-paste migration command, typed from your own field
 
 In CI, one spec calling `Rails.application.eager_load!` exercises every contract in the whole app.
 
-## Sensitive parameters and log redaction
+### Sensitive parameters and log redaction
 
 Mark a field `sensitive: true` and its name is registered with `Permittable.filter_parameter_registry`; `Permittable::Railtie` appends a filter proc to `config.filter_parameters` at boot.
 
@@ -396,7 +557,7 @@ The indirection is deliberate. Appending plain symbols to `config.filter_paramet
 
 Matching mirrors Rails' own symbol-filter semantics: case-insensitive substring match on the parameter key. The registry is fully duck-typed (`#add`, `#include?`, `#to_proc`, `#reset!`) and swappable via `Permittable.filter_parameter_registry=`, so a host gem can pool registrations into its own.
 
-## Instrumentation
+### Instrumentation
 
 Every violation emits an `ActiveSupport::Notifications` event, so rejected requests can be dashboarded and alerted on:
 
@@ -404,13 +565,29 @@ Every violation emits an `ActiveSupport::Notifications` event, so rejected reque
 ActiveSupport::Notifications.subscribe("invalid_parameters.permittable") do |*, payload|
   payload[:controller]  # "users"
   payload[:action]      # "create"
+  payload[:mode]        # :enforce, or :monitor for a would-be rejection
   payload[:details]     # [{ param: "user.age", code: "inclusion" }]
 end
 ```
 
-## Monitor mode (roll out without rejecting)
+---
+
+## Adopting on a live API
 
-Adopting contracts on a live API — or tightening one field on an existing contract — has a chicken-and-egg problem: you cannot know what the 422s would break until you enforce them, and you dare not enforce them until you know. Old mobile app versions, third-party integrations, and forgotten cron jobs all send what they send. `mode: :monitor` resolves it: the full pipeline runs (unwrap, cast, validate, defaults), but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed.
+Adding contracts to an API with real traffic has a chicken-and-egg problem: you cannot know what the 422s would break until you enforce them, and you dare not enforce them until you know. Old mobile app versions, third-party integrations, and forgotten cron jobs all send what they send.
+
+Permittable's answer is an afternoon-sized recipe:
+
+1. **Draft.** `bin/rails permittable:generate` writes a first contract for every controller from the model's columns and the `params.permit` calls already in the source. Action code stays as-is.
+2. **Monitor.** Deploy with `PERMITTABLE_MODE=monitor`. Behaviour is unchanged; every would-be rejection is logged and instrumented.
+3. **Watch.** Point your existing notification subscriber at a dashboard. Every entry is a real client that would have been rejected — fix the contract, or wait for that traffic to drain.
+4. **Enforce.** Flip to enforce, controller by controller. Every 422 you now return is one you already counted.
+
+The two halves of that recipe are below.
+
+### Monitor mode (roll out without rejecting)
+
+`mode: :monitor` runs the full pipeline — unwrap, cast, validate, defaults — but a violation is **reported instead of rejected** and the request proceeds exactly as it did before the contract existed.
 
 ```ruby
 class OrdersController < ApplicationController
@@ -434,24 +611,17 @@ Permittable.mode = ENV.fetch("PERMITTABLE_MODE", "enforce").to_sym
 On a violating request in monitor mode:
 
 - **Nothing raises and nothing renders** — the action runs.
-- The [`invalid_parameters.permittable` event](#instrumentation) fires with `mode: :monitor` in the payload (enforced violations carry `mode: :enforce`), and the logger warns with the offending paths. Point your existing subscriber at a dashboard and you have a per-controller rollout report.
-- `permitted_params` returns the **raw pass-through**: exactly what the client sent, untouched — no casts, no defaults, no transforms. A missing `root:` passes an empty hash (the envelope you asked for isn't there); a rootless contract drops only Rails' routing keys.
+- The [`invalid_parameters.permittable` event](#instrumentation) fires with `mode: :monitor` in the payload (enforced violations carry `mode: :enforce`), and the logger warns with the offending paths.
+- `permitted_params` returns the **raw pass-through**: exactly what the client sent, untouched — no casts, no defaults, no transforms. A missing `root:` passes an empty hash; a rootless contract drops only Rails' routing keys.
 - `permittable_violations` returns the recorded details (`[]` when the request was clean), if the action wants to branch on or tag the traffic.
 
 Monitor-mode rules validate **eagerly in the `before_action`, regardless of `enforce:`** — telemetry must not depend on the action calling `permitted_params`, since legacy actions still reading `params` directly are exactly the ones worth monitoring. (On a plain-Ruby host without `before_action`, validation stays lazy.)
 
-The rollout recipe:
-
-1. Write contracts for a legacy controller — or let [`permittable:generate`](#generating-draft-contracts-permittablegenerate) draft them. The action code stays as-is.
-2. Deploy with `PERMITTABLE_MODE=monitor`. Behaviour is unchanged; telemetry starts.
-3. Watch the dashboard. Every entry is a real client that would have been rejected — fix the contract, or wait for that traffic to drain.
-4. Flip to enforce, controller by controller. Every 422 you now return is one you already counted.
-
 [Exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) marks operations whose rule declares `mode: :monitor` with `x-permittable-mode: "monitor"` — the docs shouldn't promise a 422 the server doesn't yet send. Only the per-rule declaration is exported: the global `Permittable.mode` is runtime configuration, not contract data.
 
-## Generating draft contracts (`permittable:generate`)
+### Generating draft contracts (`permittable:generate`)
 
-The blank-page problem, solved: the first draft of every contract can be generated from what the app already knows — the model's columns, and the `params.permit` calls already sitting in the controller.
+The blank-page problem, solved: the first draft of every contract is generated from what the app already knows.
 
 ```sh
 bin/rails permittable:generate                      # every controller without a contract
@@ -481,11 +651,15 @@ The generator's one rule is **draft, don't guess** — everything it cannot know
 
 No Rails required for the core: `Permittable::Generator.draft(model: User)`, `.for_controller(controller, source: File.read(path))`, and `.scan(source)` are plain Ruby.
 
-Together with [monitor mode](#monitor-mode-roll-out-without-rejecting) this makes the whole adoption path one afternoon: generate drafts, paste, deploy monitoring, watch the dashboard, flip to enforce.
+---
+
+## Beyond the controller
 
-## Testing contracts (RSpec matchers)
+Because a contract is data, it has readers other than the request validator.
 
-Because a contract is data, it can be specified without dispatching a request. `require "permittable/rspec"` (in `spec_helper.rb`) auto-includes the matchers:
+### Testing contracts (RSpec matchers)
+
+A contract can be specified without dispatching a request. `require "permittable/rspec"` (in `spec_helper.rb`) auto-includes the matchers:
 
 ```ruby
 RSpec.describe UsersController do
@@ -505,7 +679,7 @@ Chains: `for_action`, `as`, `as_array(of:)`, `required` / `optional`, `within` (
 
 `for_action` picks the rule exactly like a request would (`permit_rule_for`), and may be omitted only when the controller declares a single contract — an ambiguous expectation raises instead of silently checking the wrong rule. Failure messages name what the contract actually declares.
 
-## Standalone contracts (no controller)
+### Standalone contracts (no controller)
 
 The same DSL, callable on any Hash — webhook payloads, job arguments, service-object inputs, CSV rows:
 
@@ -532,9 +706,9 @@ Everything carries over — strict coercion, `""`/`nil` absence, defaults, `fina
 - **No router-key exemption.** `unknown: :error` flags a stray `action` or `controller` key — standalone input has no router to excuse.
 - **No memoization.** Every `#call` validates fresh, so one frozen contract is safely reusable and shareable (assign it to a constant).
 
-## Exporting OpenAPI (docs that cannot drift)
+### Exporting OpenAPI (docs that cannot drift)
 
-Because a contract is data, it has a third reader beyond the validator and the drift guard: an exporter that emits **OpenAPI 3.1** (whose request bodies are plain JSON Schema). The schema is generated from the same frozen data the server enforces, so — like the drift guard, pointed outward — the docs cannot lie:
+An exporter emits **OpenAPI 3.1** (whose request bodies are plain JSON Schema) from the same frozen data the server enforces. Like the drift guard pointed outward: the docs cannot lie.
 
 ```sh
 bin/rails permittable:openapi                       # JSON to stdout
@@ -552,7 +726,16 @@ Permittable::OpenAPI.operations_for(UsersController)                    # { acti
 Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
 ```
 
-How contracts map:
+Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
+
+**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+
+Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
+
+<details>
+<summary><strong>How contracts map onto JSON Schema</strong></summary>
+
+<br>
 
 | Contract | Emitted schema |
 |---|---|
@@ -569,15 +752,15 @@ How contracts map:
 | `root:` | the wrapping object, itself required |
 | `sensitive: true` | `writeOnly: true` (never echoed in responses) |
 
-Every operation references shared components for the [error envelope](#violations-and-error-responses): a `422` response always, plus a `400` when the contract declares a `root:`. So consumers get typed *errors*, not just typed inputs.
+</details>
 
-**What is honestly unrepresentable stays visible instead of guessed.** A `format:` regexp using a Ruby-only construct (or flags) is exported as `x-permittable-pattern` rather than a mistranslated `pattern`; `validate:`/`transform:` are flagged `x-permittable-custom-validation`/`x-permittable-transformed`; actions covered only by a catch-all rule on a plain-Ruby host appear under `"*"` with `x-permittable-catch-all`; operations whose rule runs in [monitor mode](#monitor-mode-roll-out-without-rejecting) carry `x-permittable-mode: "monitor"`; operations with no matching route land in `x-permittable-controllers` instead of being dropped. The schema documents the canonical JSON encoding — the runtime additionally accepts string-encoded scalars (`"42"`, `"true"`) for form/query payloads.
+---
 
-Output is deterministic (fixed key order, declaration-order properties), so the generated file can be committed and reviewed as a diff — a contract change shows up in the same PR as its documentation change.
+## Reference
 
-## API reference
+### API
 
-### Instance methods
+**Instance methods**
 
 | Method | Purpose |
 |---|---|
@@ -586,7 +769,7 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | `enforce_params_contract` | The `before_action` entry point. Validates rules declared `enforce: true` and all [monitor-mode](#monitor-mode-roll-out-without-rejecting) rules. Public, so hosts can `skip_before_action` it |
 | `render_invalid_parameters(error)` | The `rescue_from` target. Renders via the host's `render_error` when defined, the inline envelope otherwise |
 
-### Class methods
+**Class methods**
 
 | Method | Purpose |
 |---|---|
@@ -594,9 +777,9 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | `permittable_contracts` | The frozen array of every declared rule — introspectable, testable |
 | `permit_rule_for(action)` | The last rule matching `action`, or `nil` |
 
-### Module
+**Module**
 
-| | |
+| Constant | Purpose |
 |---|---|
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
 | `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
@@ -608,10 +791,15 @@ Output is deterministic (fixed key order, declaration-order properties), so the
 | `Permittable::Contract` | [Standalone contracts](#standalone-contracts-no-controller) (`.define`, `#call`, `#call!`, `#json_schema`, `#rule`) |
 | `Permittable::Matchers` | RSpec matchers via `require "permittable/rspec"` — see [testing contracts](#testing-contracts-rspec-matchers) |
 
-## Errors caught at class load
+### Errors caught at class load
 
 A bad contract is a programmer error, so it fails when the class loads — never at request time. Every message names the field and explains the fix.
 
+<details>
+<summary><strong>The full list</strong></summary>
+
+<br>
+
 - A field declared twice in one contract
 - An unknown option for the field's kind, listing what *is* allowed
 - An unknown type, listing the supported ones
@@ -620,31 +808,40 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - `length:` that isn't a `Range` or `Integer`; `in:` that doesn't respond to `include?`
 - `validate:` or `transform:` that isn't callable
 - A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:`
+- A `default: nil` or `example: nil` on a field that isn't `nullable:`
+- A `:json` field's `default:`/`example:` that isn't a Hash, or that its own `length:`/`max_depth:` would reject
+- A `max_depth:` that isn't a positive Integer
 - `required: true` combined with `default:`
 - A field given both a type and a nested block; an array given both `of:` and a block
 - An empty contract, or a nested block declaring no sub-fields
 - `finalize` declared twice, without a block, or inside a nested block
 - `permit_params` without a block, or an invalid `unknown:` mode
+- A `root:` that isn't a single key (several top-level envelopes are a rootless contract with one nested block per key)
 - An invalid `mode:` (and `Permittable.mode =` rejects invalid values at assignment)
 - A `model:` that isn't an ActiveRecord class, or `model: true` that can't be inferred
 
-## Compatibility
+</details>
 
-| | |
+### Compatibility
+
+| Requirement | Supported |
 |---|---|
 | Ruby | >= 3.2 |
 | Rails / ActiveSupport | >= 5.0, < 9 |
 | Required dependency | `activesupport` only |
 | Optional | `actionpack` (rendering, `before_action`), `activerecord` (drift guard) |
 
+`actionpack` and `activerecord` are optional because every touchpoint is guarded with `respond_to?`/`defined?` — your app brings whatever it already has. The concern works on a plain Ruby object that responds to `params`, which is what makes it straightforward to unit-test.
+
 Using [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)? `ConcernsOnRails::Controllers::Permittable` is an alias for this module, and `sensitive:` registrations pool into that gem's shared filter registry.
 
 ## Development
 
 ```sh
 bundle install
-bundle exec rspec      # 125 examples
+bundle exec rspec                        # the suite, with a coverage report in coverage/
 bundle exec rubocop
+bundle exec ruby benchmark/overhead.rb   # a full contract vs. the params.permit call it replaces
 ```
 
 Releases are automated: bump `lib/permittable/version.rb`, add a `CHANGELOG.md` section, then push a `vX.Y.Z` tag. CI publishes to RubyGems via trusted publishing (OIDC — no API keys stored) and creates the GitHub release.

data/lib/permittable/generator.rb

@@ -19,14 +19,17 @@ module Permittable
     DEFAULT_ACTIONS = %i[create update].freeze
     SKIPPED_COLUMNS = %w[created_at updated_at].freeze
 
-    # Column type => contract type. Anything absent here (json, jsonb, hstore,
-    # binary, ...) has no faithful scalar representation and becomes a TODO
-    # comment rather than a guess.
+    # Column type => contract type. Document-shaped columns map onto the
+    # opaque `:json` field — the shape stays undeclared, which is what a
+    # jsonb column is for, and `max_depth:`/`length:` can bound it later.
+    # Anything absent here (binary, geometry, ...) has no faithful
+    # representation and becomes a TODO comment rather than a guess.
     COLUMN_TYPES = {
       string: :string, text: :string, citext: :string, uuid: :string,
       integer: :integer, bigint: :integer, float: :float, decimal: :decimal,
       boolean: :boolean, date: :date, datetime: :datetime,
-      timestamp: :datetime, timestamptz: :datetime
+      timestamp: :datetime, timestamptz: :datetime,
+      json: :json, jsonb: :json, hstore: :json
     }.freeze
 
     # What a source scan recovered from existing permit calls. `scalars` are
@@ -168,7 +171,7 @@ module Permittable
 
     def column_line(column)
       type = COLUMN_TYPES[column.type]
-      return "# TODO: #{column.name} (#{column.type}) has no scalar contract type — declare it as a nested block or an array" unless type
+      return "# TODO: #{column.name} (#{column.type}) has no contract type — declare it as a nested block or an array" unless type
 
       line = "#{required_column?(column) ? 'required' : 'optional'} :#{column.name}, :#{type}"
       line += " # database default: #{column.default.inspect}" unless column.default.nil?

data/lib/permittable/json_schema.rb

@@ -75,12 +75,29 @@ module Permittable
     def field(field, unknown: :ignore)
       schema = case field[:kind]
                when :scalar then scalar_schema(field)
+               when :json then opaque_schema(field)
                when :nested then object(field[:fields], unknown: unknown)
                when :array then array_schema(field, unknown: unknown)
                end
+      nullify!(schema, field)
       annotate(schema, field)
     end
 
+    # `nullable: true` means an explicitly-sent empty value yields null, so
+    # the type gains "null". Assigning over the existing key keeps its
+    # position, preserving deterministic emission. `enum` is the one keyword
+    # that constrains the instance rather than one type (minLength, pattern,
+    # minimum and friends only apply to instances of their own type), so a
+    # nullable enum has to list null itself or it would reject the very null
+    # the type now permits.
+    def nullify!(schema, field)
+      return schema unless field[:nullable]
+
+      schema["type"] = Array(schema["type"]) + ["null"] if schema["type"]
+      schema["enum"] += [nil] if schema.key?("enum")
+      schema
+    end
+
     def scalar_schema(field)
       schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
       apply_in!(schema, field[:in])
@@ -89,6 +106,19 @@ module Permittable
       schema
     end
 
+    # A `:json` field's shape is deliberately undeclared, so the schema says
+    # "an object" and carries only the bounds the field does declare. JSON
+    # Schema has no nesting-depth keyword, so `max_depth:` stays visible as an
+    # extension rather than being dropped or mistranslated.
+    def opaque_schema(field)
+      schema = { "type" => "object" }
+      min, max = length_bounds(field[:length])
+      schema["minProperties"] = min if min
+      schema["maxProperties"] = max if max
+      schema["x-permittable-max-depth"] = field[:max_depth] if field[:max_depth]
+      schema
+    end
+
     def array_schema(field, unknown:)
       schema = { "type" => "array" }
       min, max = length_bounds(field[:length])
@@ -183,6 +213,9 @@ module Permittable
     def json_value(value)
       case value
       when Array then value.map { |v| json_value(v) }
+      # An authored `:json` default/example is a whole hash; its values get
+      # the same re-encoding as any other authored scalar.
+      when Hash then value.to_h { |k, v| [k.to_s, json_value(v)] }
       when BigDecimal then value.to_s("F")
       when Time then value.utc.iso8601
       # DateTime subclasses Date, so it must match first.

data/lib/permittable/rspec.rb

@@ -91,6 +91,11 @@ module Permittable
         self
       end
 
+      def nullable
+        @expected[:nullable] = true
+        self
+      end
+
       # -- RSpec protocol ---------------------------------------------------
 
       def matches?(subject)
@@ -191,7 +196,7 @@ module Permittable
         when :array then "expected an array field, but it is declared with `#{field[:kind]}`" unless field[:kind] == :array
         when :of then "expected an array of :#{value}, but it is of: :#{field[:of]}" unless field[:of] == value
         when :required then required_mismatch(field, value)
-        when :virtual, :sensitive then "expected the field to be #{key}, but it is not" unless field[key]
+        when :virtual, :sensitive, :nullable then "expected the field to be #{key}, but it is not" unless field[key]
         else option_mismatch(field, key, value)
         end
       end
@@ -226,7 +231,7 @@ module Permittable
         when :array then "as an array"
         when :of then "of :#{value}"
         when :required then value ? "required" : "optional"
-        when :virtual, :sensitive then key.to_s
+        when :virtual, :sensitive, :nullable then key.to_s
         else "#{OPTION_LABELS.fetch(key)} #{value.inspect}"
         end
       end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.5.1".freeze
+  VERSION = "0.6.0".freeze
 end

data/lib/permittable.rb

@@ -34,6 +34,7 @@ require "permittable/filter_parameter_registry"
 #       optional :ssn,   :string,  sensitive: true
 #       optional :plan,  :string,  in: %w[free pro], default: "free"
 #       array    :tag_names, of: :string, length: 0..10, virtual: true
+#       optional :metadata,  :json,    max_depth: 3, length: 0..32
 #       optional :address do
 #         required :city, :string
 #         optional :zip,  :string, format: /\A\d{5}\z/
@@ -79,6 +80,17 @@ require "permittable/filter_parameter_registry"
 # request. `permittable_violations` reads the recorded details ([] when
 # the request was clean).
 #
+# THE :json FIELD — the deliberate hole. A json/jsonb column exists precisely
+# so its contents need no schema, and until it was declarable a contract could
+# only drop that key (strong parameters spells it `permit(metadata: {})`).
+# `optional :metadata, :json` passes an arbitrary Hash through untouched —
+# keys are neither filtered nor cast, and `unknown:` does not descend into it
+# — while still letting the contract bound the shape it refuses to describe:
+# `length:` caps the top-level key count, `max_depth:` caps container nesting
+# (arrays count as a level), and `validate:`/`transform:` see the whole hash.
+# Anything that is not a Hash is `invalid_type`, and the field still maps onto
+# a column for the drift guard.
+#
 # Coercion is deliberately STRICT — ActiveModel::Type is not used, because its
 # casts are lenient by design ("abc".to_i == 0, Boolean.cast("abc") == true)
 # and silently corrupting untrusted input is exactly what a contract must not
@@ -86,8 +98,16 @@ require "permittable/filter_parameter_registry"
 # guess. nil and "" are both treated as ABSENT (the query-param convention):
 # absent optional fields are OMITTED from the result (so partial updates never
 # nil-out columns), absent required fields violate, and `default:` fills
-# absence. Clearing a column to NULL is therefore outside a contract's
-# vocabulary — do that explicitly.
+# absence.
+#
+# `nullable: true` splits that rule in two for one field, which is how a PATCH
+# clears a column: a key the client never sent stays absent (defaults apply,
+# required violates), but a key sent EMPTY (JSON null, or "" from a form) is an
+# explicit null and yields nil in the result — ahead of any `default:`, and
+# without casting or checking a value that isn't there. It reads on arrays and
+# nested blocks too (the array/object itself may be null, never its elements),
+# and `default: nil` — legal only on a nullable field — gives the PUT reading
+# where absence also means clear.
 #
 # Failures raise Permittable::InvalidParameters, rescued (on a real
 # controller) into the shared ErrorEnvelope shape with `details:` entries of
@@ -134,6 +154,9 @@ module Permittable
 
   LABEL = "Permittable".freeze
   SCALAR_TYPES = %i[string integer float decimal boolean date datetime].freeze
+  # Not a scalar: an opaque hash whose shape is deliberately undeclared, for
+  # the json/jsonb column a contract has to be able to carry.
+  JSON_TYPE = :json
   UNKNOWN_MODES = %i[ignore log error].freeze
   MODES = %i[enforce monitor].freeze
   # Rails merges routing bookkeeping into params; a top-level (root: false)
@@ -245,6 +268,31 @@ module Permittable
       check_custom(field[:validate], value)
     end
 
+    # Free-form hash. The shape is deliberately undeclared, so the only
+    # checks are the bounds the field asked for: breadth (`length:`, the
+    # top-level key count, same reading as an array's element count) and
+    # nesting (`max_depth:`). Shared with macro-time `default:`/`example:`
+    # checking, like check_scalar.
+    def check_json(field, value)
+      return [:error, "invalid_type"] unless value.is_a?(Hash)
+      return [:error, "length"] if field[:length] && !length_ok?(field[:length], value.length)
+      return [:error, "depth"] if field[:max_depth] && depth_exceeds?(value, field[:max_depth])
+
+      check_custom(field[:validate], value)
+    end
+
+    # Container nesting, with the field's own hash as level 1. An Array counts
+    # as a level too — a deeply nested payload is a deeply nested payload
+    # whichever container carries it. Bails at the first breach instead of
+    # measuring the whole tree.
+    def depth_exceeds?(value, limit)
+      return false unless value.is_a?(Hash) || value.is_a?(Array)
+      return true if limit < 1
+
+      children = value.is_a?(Hash) ? value.each_value : value.each
+      children.any? { |child| depth_exceeds?(child, limit - 1) }
+    end
+
     # A custom validator returning a Symbol fails with that symbol as the
     # violation code; false/nil fails as "invalid"; any other truthy value
     # passes.
@@ -318,16 +366,37 @@ module Permittable
       [:error, "invalid_type"]
     end
 
+    # Date.parse fills in what a string omits FROM TODAY: "09/2026" becomes
+    # the 1st, "5th" becomes this month of this year. That is a guess, and a
+    # non-deterministic one — the same request means different things on
+    # different days — which is exactly what this coercion exists to refuse.
+    # So the string must name all three parts; which format it names them in
+    # is Date.parse's business, and every complete format it understands
+    # ("2026-09-05", "2026/09/05", "Sep 5, 2026") still works.
     def cast_date(value)
       case value
       when Date then [:ok, value]
-      when String then [:ok, Date.parse(value)]
+      when String
+        found = Date._parse(value)
+        return [:error, "invalid_type"] unless complete_date?(found)
+
+        # Built from the components rather than re-running Date.parse, which
+        # would parse the same string a second time — and Date.parse is the
+        # expensive half. Date.new applies the same calendar validation, so
+        # "2026-02-30" still fails.
+        [:ok, Date.new(found[:year], found[:mon], found[:mday])]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
       [:error, "invalid_type"]
     end
 
+    # Date._parse is the layer under Date.parse, and reports which components
+    # it actually FOUND rather than the filled-in result.
+    def complete_date?(found)
+      found.key?(:year) && found.key?(:mon) && found.key?(:mday)
+    end
+
     # A zoneless String parses as UTC regardless of the host timezone
     # (deterministic); explicit offsets are honoured and normalised to UTC.
     def cast_datetime(value)
@@ -335,7 +404,17 @@ module Permittable
       # DateTime is listed here, ahead of Date, because it subclasses Date.
       when ActiveSupport::TimeWithZone, Time, DateTime then [:ok, value.to_time.utc]
       when Date then [:ok, Time.utc(value.year, value.month, value.day)]
-      when String then [:ok, DateTime.parse(value).to_time.utc]
+      when String
+        # Same rule as :date — the DATE part must be named in full, or it is
+        # taken from today ("10:30" meant today at 10:30). An absent TIME part
+        # is fine and means midnight, which is the documented reading of a
+        # date given to a :datetime field.
+        #
+        # Unlike :date this still parses twice, deliberately: rebuilding a
+        # Time from components would have to reimplement DateTime.parse's
+        # handling of offsets, zone names and sub-second precision, and
+        # getting that subtly wrong costs more than the parse.
+        complete_date?(Date._parse(value)) ? [:ok, DateTime.parse(value).to_time.utc] : [:error, "invalid_type"]
       else [:error, "invalid_type"]
       end
     rescue ArgumentError, RangeError
@@ -365,9 +444,13 @@ module Permittable
   # declaration is validated eagerly: a bad contract is a programmer error and
   # should fail at class load, not at request time.
   class ContractBuilder
-    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example].freeze
-    NESTED_OPTS = %i[virtual sensitive message desc].freeze
-    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example].freeze
+    SCALAR_OPTS = %i[in format length default normalize validate virtual sensitive transform message desc example
+                     nullable].freeze
+    NESTED_OPTS = %i[virtual sensitive message desc nullable].freeze
+    JSON_OPTS   = %i[length max_depth default validate virtual sensitive transform message desc example
+                     nullable].freeze
+    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message desc example
+                     nullable].freeze
 
     attr_reader :finalizer
 
@@ -437,6 +520,12 @@ module Permittable
         field = { name: name, kind: :nested, required: required,
                   fields: nested_fields!(name, &block), **opts }
         validate_message!(field)
+      elsif type&.to_sym == JSON_TYPE
+        assert_opts!(name, opts, JSON_OPTS)
+        # `type:` is carried alongside `kind:` so the same `as(:json)` matcher
+        # chain and the same error wording work as for a scalar.
+        field = { name: name, kind: :json, required: required, type: JSON_TYPE, **opts }
+        validate_json_opts!(field)
       else
         assert_opts!(name, opts, SCALAR_OPTS)
         field = { name: name, kind: :scalar, required: required,
@@ -500,6 +589,40 @@ module Permittable
       validate_message!(field)
     end
 
+    def validate_json_opts!(field)
+      name = field[:name]
+      if field[:required] && field.key?(:default)
+        raise ArgumentError, "#{LABEL}: field :#{name} is required and cannot have a :default (default implies optional)"
+      end
+
+      validate_length!(name, field[:length]) if field.key?(:length)
+      validate_max_depth!(name, field[:max_depth]) if field.key?(:max_depth)
+      validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
+      validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
+      validate_json_authored_value!(field, :default)
+      validate_json_authored_value!(field, :example)
+      validate_message!(field)
+    end
+
+    def validate_max_depth!(name, depth)
+      return if depth.is_a?(Integer) && depth.positive?
+
+      raise ArgumentError, "#{LABEL}: :max_depth for :#{name} must be a positive Integer"
+    end
+
+    # Same rule as a scalar's authored value, over check_json: a `default:` or
+    # `example:` that its own bounds would reject fails at class load.
+    def validate_json_authored_value!(field, opt)
+      return unless field.key?(opt)
+      return if authored_nil!(field, opt)
+      raise ArgumentError, "#{LABEL}: :#{opt} for :#{field[:name]} must be a Hash" unless field[opt].is_a?(Hash)
+
+      status, code = Coercion.check_json(field, field[opt])
+      return if status == :ok
+
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
+    end
+
     # format / length / normalize reason about characters; on any other
     # type they would silently apply to a cast non-String and mislead.
     def validate_string_only_opts!(field)
@@ -540,6 +663,7 @@ module Permittable
     # shipping it to every request (or publishing it in generated docs).
     def validate_authored_value!(field, opt)
       return unless field.key?(opt)
+      return if authored_nil!(field, opt)
 
       status, code = Coercion.check_scalar(field, field[opt])
       return if status == :ok
@@ -549,6 +673,7 @@ module Permittable
 
     def validate_array_authored_value!(field, opt)
       value = field[opt]
+      return if authored_nil!(field, opt)
       raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
       return unless field[:of]
 
@@ -560,6 +685,19 @@ module Permittable
       end
     end
 
+    # An authored nil is only meaningful on a nullable field, where it says
+    # "absent means clear" (PUT semantics) rather than "no default". On any
+    # other field it is a value nil could never satisfy, so it fails at class
+    # load with the fix named.
+    def authored_nil!(field, opt)
+      return false unless field[opt].nil?
+      return true if field[:nullable]
+
+      raise ArgumentError,
+            "#{LABEL}: :#{opt} for field :#{field[:name]} is nil but the field is not nullable — " \
+            "declare nullable: true to make an explicit null part of the contract"
+    end
+
     # `message:` customizes what the client reads for a violation on this
     # field: one String covering every code, or a Hash of code => String
     # (codes without an entry keep the default rendering). Keys are
@@ -694,9 +832,10 @@ module Permittable
     end
 
     # The drift guard. Nested/array fields are implicitly virtual — only
-    # scalar fields map one-to-one onto columns.
+    # scalar fields, and the opaque `:json` field standing in for a
+    # json/jsonb column, map one-to-one onto columns.
     def guard_contract_columns!(model_class, fields)
-      checked = fields.select { |f| f[:kind] == :scalar && !f[:virtual] }
+      checked = fields.select { |f| %i[scalar json].include?(f[:kind]) && !f[:virtual] }
       return if checked.empty?
 
       types = checked.to_h { |f| [f[:name], f[:type]] }
@@ -903,7 +1042,9 @@ module Permittable
       value = hash[key]
 
       if permittable_absent?(value, hash, key)
-        if field.key?(:default)
+        if permittable_explicit_null?(field, hash, key)
+          result[key] = nil
+        elsif field.key?(:default)
           result[key] = field[:default]
         elsif field[:required]
           violations << permittable_violation(field, full, "missing")
@@ -921,13 +1062,9 @@ module Permittable
     key = field[:name].to_s
     case field[:kind]
     when :scalar
-      status, out = Coercion.check_scalar(field, value)
-      if status == :ok
-        out = field[:transform].call(out) if field[:transform]
-        result[key] = out
-      else
-        violations << permittable_violation(field, full, out)
-      end
+      permittable_check_whole(field, Coercion.check_scalar(field, value), full, result, violations: violations)
+    when :json
+      permittable_check_whole(field, Coercion.check_json(field, value), full, result, violations: violations)
     when :nested
       if value.is_a?(Hash)
         result[key] = permittable_check_hash(field[:fields], ActiveSupport::HashWithIndifferentAccess.new(value),
@@ -944,6 +1081,19 @@ module Permittable
     end
   end
 
+  # The shared tail of the two kinds whose entire value is checked in one
+  # call — a scalar, or an opaque hash. A clean value is transformed into the
+  # result; anything else records its code.
+  def permittable_check_whole(field, outcome, full, result, violations:)
+    status, out = outcome
+    if status == :ok
+      out = field[:transform].call(out) if field[:transform]
+      result[field[:name].to_s] = out
+    else
+      violations << permittable_violation(field, full, out)
+    end
+  end
+
   def permittable_check_array(field, value, path:, unknown:, violations:)
     before = violations.length
     violations << permittable_violation(field, path, "length") if field[:length] && !Coercion.length_ok?(field[:length], value.length)
@@ -982,6 +1132,15 @@ module Permittable
     !hash.key?(key) || value.nil? || (value.is_a?(String) && value.empty?)
   end
 
+  # `nullable: true` splits the one absence rule in two: a key the client
+  # never sent is still absent (defaults apply, required violates), but a key
+  # sent EMPTY is an explicit null — the field yields nil, so a PATCH can
+  # clear a column. Nothing is cast or checked: there is no value to check,
+  # and `transform:` never sees a nil it did not agree to.
+  def permittable_explicit_null?(field, hash, key)
+    field[:nullable] && hash.key?(key)
+  end
+
   def permittable_check_unknown(fields, hash, path:, unknown:, top_level:, violations:)
     return if unknown == :ignore
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-02 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport