permittable 0.5.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24ca6a6f3f19fec065cb3ac2edcc255131e0b3e6093b1a0f1b860b31a9798597
-  data.tar.gz: 639aa236702384c0762a5ee694835115fdbd9ed677bf16824bff4618f1aa6cb9
+  metadata.gz: ddca88b2da7672d0995e338ab901188c4ba019f4d5928d7aaf0a5f73a7f8ba9c
+  data.tar.gz: 1a66ef88adc7ab843798f25c7a5e3444a3e550795d1353139d52b65e05ac5005
 SHA512:
-  metadata.gz: 852e4234d867bda50477812978c1327132b87e76297fddf9f53d5a62b5e65545bf76bb2955dc2f0deb0fc3a4a547b88ca782a8a12fc03cb3ac7287f78f07c869
-  data.tar.gz: 7b850f5b1cc806cf3044c4fb27dcd59f270ff8d0a504ab5fd8e757d9d284df8c03e9182aafffd1e9c538524798e6620b76c621890832e5656dc29b9ae1c4b70a
+  metadata.gz: 7288c663fd8a2d740ca1c1e7fe9ad61d50854fa47e0e9c4a75bb0922bd119d7c4ca9fe99b020b6ea03edfb456d0fe88322161d53cc1bdd71afb6b88f6cf6ccda
+  data.tar.gz: a9ecd5c620fac068991a0401d76f339163eb20b6bed73ab83a33f5c3895f8bfb82479a86ab9d6385d85321732ce8ebc6c332819b32174bc8d0494c6021d1623f

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 <!-- 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 -->
 

data/README.md

@@ -179,7 +179,9 @@ Adopting on an existing API with live traffic? Skip ahead to [Adopting on a live
   - [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)
@@ -272,6 +274,9 @@ 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
 ```
 
 Arrays are **optional unless `required: true`**, and `length:` on an array constrains the element **count**.
@@ -293,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.
 
@@ -316,14 +323,46 @@ 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.
 
+### 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.
@@ -336,10 +375,39 @@ That single rule produces the behaviour you want from a `PATCH`:
 | absent and **required** | a `missing` violation |
 | absent with a **`default:`** | the default — a defaulted field can never report `missing` |
 
-Declaring `required:` alongside `default:` is a class-load error, since a default implies optionality. And 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.
 
+### Explicit nulls (`nullable:`)
+
+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).
@@ -740,6 +808,9 @@ 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

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.2".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.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-06 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport