permittable 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 577c3a6c767e85dd2b3fc0ad8049e1d0ec77d2b87bc1f6eedca351161f589ef9
-  data.tar.gz: bed2c92d56a70abf45f8f9cc4b779788886623b442054d63727893f891eb0c13
+  metadata.gz: aa679480fdac311694469096c7537926586e987ce2e7a724099611ec91dd3d2b
+  data.tar.gz: fa1785c674f0cbf388ce9f74b87f22344adef95cd5a5bfa6c81490fb8958a124
 SHA512:
-  metadata.gz: bd955e930e66036f2bffd9f006996ad0713e3582eda8386e51bc668d42432db7f941bef9724ba5c6589e85be4ce91827cc8536f49ca6c0d698562de0aee65520
-  data.tar.gz: a61f63950413801e405a6690e141a35616d974cc347bdae86e9a6f239a75e89225604b973acb4daf4b7daa25492e767175f674de6376df62eb0128e27f16fa62
+  metadata.gz: 66e7a85dad6e8029dbc8827b1a55ac14a297e3dc006315ffc66efc0e2f7dd6179ee6247e33f5de93a06d7fe08c3ff1205e30bf6dde6b16d93bfd381bdd3da813
+  data.tar.gz: fc0e4a920d62a687c960b808301841327bde86c85a2cf90c36c65e0ac61f133844e0733cd6ad3075298a8680d5a1360e9319495c4e60a9382449047bf6d76c0e

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 <!-- CHANGELOG.md -->
 
+## 0.3.0 (2026-08-24)
+<!-- title: OpenAPI export -->
+
+Contracts gain a third reader. The registry that already drives the validator and the schema-drift guard now also generates **OpenAPI 3.1** — because the schema is emitted from the same frozen data the server enforces, the docs cannot drift from the validation. Fully additive; no behaviour of existing contracts changes.
+
+### Added
+- **`Permittable::JsonSchema`** — converts rules and fields into JSON Schema (draft 2020-12): types map onto their canonical JSON encodings (`:decimal` as `["string", "number"]` + `format: decimal`), `in:` → `enum`/`minimum`/`maximum`, `length:` → `minLength`/`maxLength` or `minItems`/`maxItems`, `format:` → `pattern` with `\A`/`\z` translated to `^`/`$`, `default:` → `default`, `unknown: :error` → `additionalProperties: false` at every level, `root:` → a required wrapper object, `sensitive:` → `writeOnly: true`. Required strings get `minLength: 1` (`""` is absent). What has no ECMA/JSON-Schema equivalent stays visible instead of guessed: Ruby-only or flagged regexps export as `x-permittable-pattern`, `validate:`/`transform:` as `x-permittable-custom-validation`/`x-permittable-transformed`, non-numeric Ranges as `x-permittable-range`. Emission is deterministic, so generated documents are committable and diff-stable.
+- **`Permittable::OpenAPI`** — assembles full OpenAPI 3.1 documents (`.document`) and fragments (`.request_body_for`, `.operations_for`, `.components`) from any set of controllers, plain Ruby, no Rails required. Operations resolve through `permit_rule_for`, so last-matching-rule-wins holds in the docs exactly as at request time; every operation references shared components typing the 422 (and, for rooted contracts, 400) error envelope. Catch-all rules expand through `action_methods` (the concern's own public methods excluded) or surface as `"*"` + `x-permittable-catch-all`; unrouted operations land in `x-permittable-controllers` rather than being dropped.
+- **`bin/rails permittable:openapi[output]`** — rake task (loaded by the Railtie) that eager-loads the app, collects every controller with contracts, maps actions onto `paths` via the route set (`:id` → `{id}`), and prints or writes the document. `OPENAPI_TITLE`/`OPENAPI_VERSION` override the `info` block.
+- **`desc:` and `example:` field options, `desc:` on `permit_params`** — documentation passthrough carried on the frozen contract data and ignored by the runtime. An `example:` is validated against its own field's contract at class load, exactly like `default:`, so published examples can't lie either.
+
 ## 0.2.0 (2026-08-18)
 <!-- title: custom error messages -->
 

data/README.md

@@ -54,6 +54,7 @@ A violating request never reaches your action:
 - [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)
+- [Exporting OpenAPI](#exporting-openapi-docs-that-cannot-drift)
 - [API reference](#api-reference) · [Errors caught at class load](#errors-caught-at-class-load) · [Compatibility](#compatibility)
 
 ---
@@ -70,6 +71,7 @@ A violating request never reaches your action:
 | Machine-readable error details | ❌ | ❌ | ✅ |
 | Reshapes output | ❌ | ❌ | ✅ |
 | Checked against your schema at boot | ❌ | ❌ | ✅ |
+| Exports OpenAPI / JSON Schema | ❌ | ❌ | ✅ |
 
 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.
 
@@ -109,7 +111,7 @@ Validation is **lazy by default**: it runs on the first `permitted_params` call,
 ## Declaring a contract
 
 ```ruby
-permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &contract)
+permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, desc: nil, &contract)
 ```
 
 | Option | Default | Meaning |
@@ -119,6 +121,7 @@ permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: fals
 | `model:` | `nil` | Model class, or `true` to infer from `controller_name`, enabling the [drift guard](#the-schema-drift-guard) |
 | `unknown:` | `:ignore` | `:ignore` / `:log` / `:error` — how to treat undeclared keys |
 | `enforce:` | `false` | `false` validates lazily on first use; `true` validates in a `before_action` |
+| `desc:` | `nil` | Documentation only — becomes the operation description in [exported OpenAPI](#exporting-openapi-docs-that-cannot-drift) |
 
 `permit_params` is **repeatable**, and **the last matching rule wins**. Contracts behave like configuration: a base controller declares a catch-all, and a subclass overrides it for specific actions.
 
@@ -186,6 +189,8 @@ Which options are legal depends on the field kind — anything else raises at cl
 | `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`) |
 | `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:` |
 
 ¹ `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.
 
@@ -378,6 +383,49 @@ ActiveSupport::Notifications.subscribe("invalid_parameters.permittable") do |*,
 end
 ```
 
+## 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:
+
+```sh
+bin/rails permittable:openapi                       # JSON to stdout
+bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
+```
+
+The task eager-loads the app (also exercising the drift guard), collects every controller with contracts, and maps documented actions onto `paths` via the route set. `OPENAPI_TITLE` / `OPENAPI_VERSION` override the `info` block. Pipe the output through Swagger UI, Redoc, Postman, or [`openapi-typescript`](https://github.com/openapi-ts/openapi-typescript) and your frontend gets compile-time types for every request body.
+
+Or build fragments programmatically — no Rails required:
+
+```ruby
+Permittable::JsonSchema.rule(UsersController.permit_rule_for(:create))  # request-body schema
+Permittable::OpenAPI.request_body_for(UsersController, :create)         # OpenAPI requestBody object
+Permittable::OpenAPI.operations_for(UsersController)                    # { action => operation }
+Permittable::OpenAPI.document(controllers: [...], info: { "title" => "My API" })
+```
+
+How contracts map:
+
+| Contract | Emitted schema |
+|---|---|
+| `required` / `optional` | the object's `required:` array; required strings also get `minLength: 1` (`""` is absent) |
+| `:string` `:integer` `:float` `:boolean` | `string` / `integer` / `number` / `boolean` |
+| `:date` / `:datetime` | `string` + `format: date` / `date-time` |
+| `:decimal` | `type: ["string", "number"]` + `format: decimal` (string is the precision-safe encoding) |
+| `in:` Array / numeric Range | `enum` / `minimum` + `maximum` (exclusive ends honoured) |
+| `length:` | `minLength`/`maxLength` on strings, `minItems`/`maxItems` on arrays |
+| `format:` | `pattern`, with `\A`/`\z` translated to `^`/`$` |
+| `default:` / `desc:` / `example:` | `default` / `description` / `examples` |
+| nested block / `array` | `object` + `properties` / `array` + `items` |
+| `unknown: :error` | `additionalProperties: false`, at every nesting level |
+| `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.
+
+**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 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.
+
 ## API reference
 
 ### Instance methods
@@ -403,6 +451,8 @@ end
 | `Permittable.filter_parameter_registry` | The live registry of `sensitive:` field names |
 | `Permittable.filter_parameter_registry=` | Swap in your own duck-typed registry |
 | `Permittable::InvalidParameters` | Raised on violation; carries `#details` and `#status` |
+| `Permittable::JsonSchema` | Contract data → JSON Schema fragments (`.rule`, `.object`, `.field`) |
+| `Permittable::OpenAPI` | OpenAPI 3.1 assembly (`.document`, `.operations_for`, `.request_body_for`, `.components`) |
 
 ## Errors caught at class load
 
@@ -415,7 +465,7 @@ A bad contract is a programmer error, so it fails when the class loads — never
 - `format:`, `length:`, or `normalize:` on a non-`:string` field
 - `length:` that isn't a `Range` or `Integer`; `in:` that doesn't respond to `include?`
 - `validate:` or `transform:` that isn't callable
-- A `default:` that violates its own field's contract, or an array `default:` whose elements violate `of:`
+- A `default:` or `example:` that violates its own field's contract, or an array `default:`/`example:` whose elements violate `of:`
 - `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
@@ -438,7 +488,7 @@ Using [concerns_on_rails](https://github.com/VSN2015/concerns_on_rails)? `Concer
 
 ```sh
 bundle install
-bundle exec rspec      # 76 examples
+bundle exec rspec      # 112 examples
 bundle exec rubocop
 ```
 

data/lib/permittable/json_schema.rb

@@ -0,0 +1,196 @@
+module Permittable
+  # Converts frozen contract data — the rule and field hashes built by
+  # ContractBuilder — into JSON Schema (draft 2020-12, the dialect OpenAPI 3.1
+  # request bodies use). This is the third reader of the contract registry,
+  # after the request validator and the column guard: because a contract is
+  # data, a schema exported from it cannot drift from what the server
+  # actually enforces.
+  #
+  # The exported schema describes the DECLARED INPUT SHAPE in its canonical
+  # JSON encoding. Two deliberate consequences:
+  #   * Coercion additionally accepts string-encoded scalars ("42", "true")
+  #     for form/query payloads; the schema documents the JSON types only.
+  #   * `validate:`/`transform:`/`finalize` are opaque callables — they never
+  #     change what a client may SEND, so fields carrying them are flagged
+  #     with `x-permittable-*` extensions rather than mistranslated.
+  #
+  # Emission is deterministic (fixed key insertion order, declaration-order
+  # properties) so generated documents are committable and diff-stable.
+  module JsonSchema
+    module_function
+
+    SCALAR_SCHEMAS = {
+      string: { "type" => "string" },
+      integer: { "type" => "integer" },
+      float: { "type" => "number" },
+      # Coercion accepts Numeric or String for :decimal; string is the
+      # precision-safe form, so both encodings are documented.
+      decimal: { "type" => %w[string number], "format" => "decimal" },
+      boolean: { "type" => "boolean" },
+      date: { "type" => "string", "format" => "date" },
+      datetime: { "type" => "string", "format" => "date-time" }
+    }.freeze
+
+    # Ruby regexp constructs with no ECMA-262 equivalent (\Z, \h, \K, \R, \G,
+    # inline flag groups, absence operator, conditionals, POSIX classes,
+    # possessive quantifiers). A source matching this is left untranslated —
+    # the scan is deliberately over-eager on escaped lookalikes because a
+    # wrong pattern in published docs is worse than a missing one.
+    UNTRANSLATABLE = /
+      \\[ZhHKRG]          |
+      \(\?[a-z-]+[:)]     |
+      \(\?~               |
+      \(\?\(              |
+      \[\[:               |
+      [*+?]\+
+    /x
+
+    # Request-body schema for one rule from `permittable_contracts` /
+    # `permit_rule_for`: the object schema of its fields, wrapped in the
+    # `root:` envelope when the rule declares one. The wrapper itself stays
+    # permissive even under `unknown: :error` — the runtime never inspects
+    # sibling keys outside the root.
+    def rule(permit_rule)
+      schema = object(permit_rule[:fields], unknown: permit_rule[:unknown])
+      return schema unless permit_rule[:root]
+
+      root = permit_rule[:root].to_s
+      { "type" => "object", "properties" => { root => schema }, "required" => [root] }
+    end
+
+    # Object schema for a field list; `unknown:` applies at every nesting
+    # level, exactly like the runtime check.
+    def object(fields, unknown: :ignore)
+      schema = {
+        "type" => "object",
+        "properties" => fields.to_h { |f| [f[:name].to_s, field(f, unknown: unknown)] }
+      }
+      required = fields.select { |f| f[:required] }.map { |f| f[:name].to_s }
+      schema["required"] = required unless required.empty?
+      schema["additionalProperties"] = false if unknown == :error
+      schema
+    end
+
+    # Schema fragment for one field hash of any kind.
+    def field(field, unknown: :ignore)
+      schema = case field[:kind]
+               when :scalar then scalar_schema(field)
+               when :nested then object(field[:fields], unknown: unknown)
+               when :array then array_schema(field, unknown: unknown)
+               end
+      annotate(schema, field)
+    end
+
+    def scalar_schema(field)
+      schema = SCALAR_SCHEMAS.fetch(field[:type]).dup
+      apply_in!(schema, field[:in])
+      apply_string_bounds!(schema, field)
+      apply_pattern!(schema, field[:format])
+      schema
+    end
+
+    def array_schema(field, unknown:)
+      schema = { "type" => "array" }
+      min, max = length_bounds(field[:length])
+      schema["minItems"] = min if min
+      schema["maxItems"] = max if max
+      schema["items"] = field[:fields] ? object(field[:fields], unknown: unknown) : SCALAR_SCHEMAS.fetch(field[:of]).dup
+      schema
+    end
+
+    def apply_in!(schema, allowed)
+      return unless allowed
+
+      unless allowed.is_a?(Range)
+        schema["enum"] = allowed.map { |v| json_value(v) }
+        return
+      end
+      # Runtime bounds-checks Ranges with cover?; numeric endpoints map onto
+      # minimum/maximum, anything else (a Range of strings) has no JSON
+      # Schema equivalent and is carried as an extension.
+      unless allowed.begin.is_a?(Numeric) || allowed.end.is_a?(Numeric)
+        schema["x-permittable-range"] = allowed.inspect
+        return
+      end
+      schema["minimum"] = json_value(allowed.begin) if allowed.begin
+      schema[allowed.exclude_end? ? "exclusiveMaximum" : "maximum"] = json_value(allowed.end) if allowed.end
+    end
+
+    def apply_string_bounds!(schema, field)
+      return unless field[:type] == :string
+
+      min, max = length_bounds(field[:length])
+      # "" is ABSENT and an absent required field violates, so a required
+      # string can never validly be empty — the schema says so.
+      min = 1 if field[:required] && min.to_i < 1
+      schema["minLength"] = min if min
+      schema["maxLength"] = max if max
+    end
+
+    def apply_pattern!(schema, regexp)
+      return unless regexp
+
+      pattern = ecma_pattern(regexp)
+      if pattern
+        schema["pattern"] = pattern
+      else
+        schema["x-permittable-pattern"] = regexp.inspect
+      end
+    end
+
+    # Conservative Ruby → ECMA-262 translation: \A/\z anchors become ^/$.
+    # Flagged regexps bail entirely (JSON Schema's `pattern` has no flag
+    # slot, and /x//m/i all change semantics), as does any source containing
+    # an untranslatable construct.
+    def ecma_pattern(regexp)
+      return nil unless regexp.options.zero?
+
+      source = regexp.source
+      return nil if source.match?(UNTRANSLATABLE)
+
+      source.gsub('\A', "^").gsub('\z', "$")
+    end
+
+    # length: reasons about characters on strings and element count on
+    # arrays; either way it is an exact Integer or a Range (possibly endless
+    # / beginless, possibly exclusive).
+    def length_bounds(spec)
+      case spec
+      when Integer then [spec, spec]
+      when Range
+        max = spec.end && spec.exclude_end? ? spec.end - 1 : spec.end
+        [spec.begin, max]
+      else [nil, nil]
+      end
+    end
+
+    # Documentation keys shared by every field kind. `default:`/`example:`
+    # are authored values (possibly Date/Time/BigDecimal literals), so they
+    # are re-encoded as JSON scalars.
+    def annotate(schema, field)
+      schema["default"] = json_value(field[:default]) if field.key?(:default)
+      schema["examples"] = [json_value(field[:example])] if field.key?(:example)
+      schema["description"] = field[:desc] if field[:desc]
+      if field[:sensitive]
+        schema["writeOnly"] = true
+        schema["x-permittable-sensitive"] = true
+      end
+      schema["x-permittable-custom-validation"] = true if field[:validate]
+      schema["x-permittable-transformed"] = true if field[:transform]
+      schema
+    end
+
+    def json_value(value)
+      case value
+      when Array then value.map { |v| json_value(v) }
+      when BigDecimal then value.to_s("F")
+      when Time then value.utc.iso8601
+      # DateTime subclasses Date, so it must match first.
+      when DateTime then value.to_time.utc.iso8601
+      when Date then value.iso8601
+      when Symbol then value.to_s
+      else value
+      end
+    end
+  end
+end

data/lib/permittable/open_api.rb

@@ -0,0 +1,212 @@
+require "permittable/version"
+require "permittable/json_schema"
+
+module Permittable
+  # Assembles OpenAPI 3.1 fragments and documents from Permittable contracts.
+  # Plain Ruby over the frozen contract registry — Rails is not required; the
+  # `permittable:openapi` rake task (loaded by the Railtie) supplies the
+  # Rails-only parts: eager loading, controller discovery, and the route
+  # descriptors that turn operations into real `paths` entries.
+  #
+  # Everything the exporter cannot know is left visible rather than guessed:
+  # actions covered only by a catch-all rule on a host without
+  # `action_methods` appear under the "*" key with `x-permittable-catch-all`,
+  # and operations with no matching route land in `x-permittable-controllers`
+  # instead of being dropped silently.
+  module OpenAPI
+    module_function
+
+    # The error envelope rendered by render_invalid_parameters (see
+    # ErrorEnvelope): code/details are present on every violation this gem
+    # raises, message always.
+    ERROR_SCHEMA = {
+      "type" => "object",
+      "properties" => {
+        "success" => { "type" => "boolean", "enum" => [false] },
+        "error" => {
+          "type" => "object",
+          "properties" => {
+            "message" => { "type" => "string" },
+            "code" => { "type" => "string", "enum" => ["invalid_parameters"] },
+            "details" => {
+              "type" => "array",
+              "items" => {
+                "type" => "object",
+                "properties" => {
+                  "param" => {
+                    "type" => "string",
+                    "description" => "Fully-qualified parameter path, e.g. user.address.zip or line_items[1].sku"
+                  },
+                  "code" => {
+                    "type" => "string",
+                    "description" => "missing / invalid_type / inclusion / format / length / unknown / invalid, " \
+                                     "or a contract-specific symbol"
+                  }
+                },
+                "required" => %w[param code]
+              }
+            }
+          },
+          "required" => %w[message]
+        }
+      },
+      "required" => %w[success error]
+    }.freeze
+
+    # Instance methods the concern itself adds to every including controller;
+    # action_methods reports them as actions (they are public by design), but
+    # they are never routed and must not be documented as endpoints. Resolved
+    # lazily — at file-load time the concern's module body may not have run.
+    def concern_methods
+      @concern_methods ||= Permittable.public_instance_methods(false).map(&:to_s).freeze
+    end
+
+    # Shared `components` for any document referencing Permittable responses.
+    def components
+      {
+        "schemas" => { "PermittableInvalidParameters" => ERROR_SCHEMA },
+        "responses" => {
+          "PermittableBadRequest" => error_response(
+            "The root: key is missing or not an object — the request envelope itself is malformed."
+          ),
+          "PermittableUnprocessableEntity" => error_response(
+            "One or more parameters violated the action's contract; details names each offender."
+          )
+        }
+      }
+    end
+
+    def error_response(description)
+      {
+        "description" => description,
+        "content" => {
+          "application/json" => {
+            "schema" => { "$ref" => "#/components/schemas/PermittableInvalidParameters" }
+          }
+        }
+      }
+    end
+
+    # OpenAPI requestBody object for the contract covering `action`, nil when
+    # no contract does. `required` mirrors the runtime: a rooted contract
+    # rejects a bodyless request outright (400), and so does any top-level
+    # required field (missing).
+    def request_body_for(controller, action)
+      rule = controller.permit_rule_for(action)
+      rule && rule_request_body(rule)
+    end
+
+    def rule_request_body(rule)
+      {
+        "required" => !!(rule[:root] || rule[:fields].any? { |f| f[:required] }),
+        "content" => { "application/json" => { "schema" => JsonSchema.rule(rule) } }
+      }
+    end
+
+    # { action => operation } for every action the controller's contracts
+    # cover, resolved through permit_rule_for so last-matching-rule-wins holds
+    # in the documentation exactly as it does at request time.
+    def operations_for(controller)
+      documented_actions(controller).to_h { |action| [action, operation_for(controller, action)] }
+    end
+
+    # Explicitly-declared actions in declaration order; when a catch-all rule
+    # exists, the controller's remaining action_methods (sorted) follow — or
+    # the literal "*" on hosts without action_methods (plain-Ruby params
+    # ducks), where the covered action set is unknowable.
+    def documented_actions(controller)
+      contracts = controller.permittable_contracts
+      explicit = contracts.flat_map { |rule| rule[:actions] }.uniq
+      return explicit unless contracts.any? { |rule| rule[:actions].empty? }
+      return explicit + ["*"] unless controller.respond_to?(:action_methods)
+
+      explicit + (controller.action_methods.map(&:to_s).sort - explicit - concern_methods)
+    end
+
+    def operation_for(controller, action)
+      rule = if action == "*"
+               controller.permittable_contracts.reverse_each.find { |r| r[:actions].empty? }
+             else
+               controller.permit_rule_for(action)
+             end
+      operation = {}
+      key = controller_key(controller)
+      operation["operationId"] = "#{key.tr('/', '_')}_#{action}" if key && action != "*"
+      operation["description"] = rule[:desc] if rule[:desc]
+      operation["requestBody"] = rule_request_body(rule)
+      operation["responses"] = responses_for(rule)
+      operation["x-permittable-catch-all"] = true if action == "*"
+      operation
+    end
+
+    def responses_for(rule)
+      responses = {}
+      responses["400"] = { "$ref" => "#/components/responses/PermittableBadRequest" } if rule[:root]
+      responses["422"] = { "$ref" => "#/components/responses/PermittableUnprocessableEntity" }
+      responses
+    end
+
+    # A complete OpenAPI 3.1 document. `routes:` is an optional array of
+    # { controller:, action:, verb:, path: } descriptors (see rails_routes);
+    # operations with a matching descriptor become `paths` entries, the rest
+    # are grouped by controller under `x-permittable-controllers`.
+    def document(controllers:, info: {}, routes: nil)
+      paths = {}
+      unrouted = {}
+      controllers.each do |controller|
+        operations = operations_for(controller)
+        next if operations.empty?
+
+        place_operations(controller, operations, routes, paths, unrouted)
+      end
+      doc = {
+        "openapi" => "3.1.0",
+        "info" => { "title" => "Permittable contracts", "version" => VERSION }.merge(info),
+        "paths" => paths,
+        "components" => components
+      }
+      doc["x-permittable-controllers"] = unrouted unless unrouted.empty?
+      doc
+    end
+
+    def place_operations(controller, operations, routes, paths, unrouted)
+      key = controller_key(controller) || controller.inspect
+      operations.each do |action, operation|
+        matched = routes_for(routes, key, action)
+        if matched.empty?
+          (unrouted[key] ||= {})[action] = operation
+        else
+          matched.each { |route| (paths[route[:path]] ||= {})[route[:verb].to_s.downcase] = operation }
+        end
+      end
+    end
+
+    def routes_for(routes, controller_key, action)
+      return [] if routes.nil? || action == "*"
+
+      routes.select { |r| r[:controller].to_s == controller_key && r[:action].to_s == action }
+    end
+
+    # { controller:, action:, verb:, path: } descriptors from a Rails
+    # application's route set. Duck-typed against Journey routes (each one
+    # responds to requirements / verb / path.spec) so it stays unit-testable
+    # without Rails; Rails path params (:id) become OpenAPI templates ({id}).
+    def rails_routes(app)
+      app.routes.routes.filter_map do |route|
+        requirements = route.requirements
+        verb = route.verb.to_s
+        next if requirements[:controller].nil? || requirements[:action].nil? || verb.empty?
+
+        path = route.path.spec.to_s.sub("(.:format)", "").gsub(/:(\w+)/) { "{#{Regexp.last_match(1)}}" }
+        { controller: requirements[:controller], action: requirements[:action],
+          verb: verb.split("|").first.downcase, path: path }
+      end
+    end
+
+    def controller_key(controller)
+      return controller.controller_path if controller.respond_to?(:controller_path)
+
+      controller.name
+    end
+  end
+end

data/lib/permittable/railtie.rb

@@ -12,5 +12,9 @@ module Permittable
       filter = ::Permittable.filter_parameter_registry.to_proc
       app.config.filter_parameters << filter unless app.config.filter_parameters.include?(filter)
     end
+
+    rake_tasks do
+      load File.expand_path("tasks/openapi.rake", __dir__)
+    end
   end
 end

data/lib/permittable/tasks/openapi.rake

@@ -0,0 +1,44 @@
+# Exports every Permittable contract in the app as an OpenAPI 3.1 document —
+# the docs-that-cannot-drift counterpart to the schema-drift guard. Eager
+# loading makes every controller's permit_params macro run (also exercising
+# the drift guard), then the route set maps documented actions onto paths.
+#
+#   bin/rails permittable:openapi                       # JSON to stdout
+#   bin/rails "permittable:openapi[openapi/api.json]"   # write to a file
+#
+# OPENAPI_TITLE / OPENAPI_VERSION override the document's info block.
+require "json"
+require "fileutils"
+
+namespace :permittable do
+  desc "Export an OpenAPI 3.1 document generated from every Permittable contract"
+  task :openapi, [:output] => :environment do |_t, task_args|
+    Rails.application.eager_load!
+
+    bases = []
+    bases << ActionController::Base if defined?(ActionController::Base)
+    bases << ActionController::API if defined?(ActionController::API)
+    controllers = bases.flat_map(&:descendants).uniq.select do |controller|
+      controller.respond_to?(:permittable_contracts) && controller.permittable_contracts.any?
+    end
+
+    document = Permittable::OpenAPI.document(
+      controllers: controllers,
+      routes: Permittable::OpenAPI.rails_routes(Rails.application),
+      info: {
+        "title" => ENV.fetch("OPENAPI_TITLE") { "#{Rails.application.class.module_parent_name} API" },
+        "version" => ENV.fetch("OPENAPI_VERSION", "1.0.0")
+      }
+    )
+
+    json = "#{JSON.pretty_generate(document)}\n"
+    if task_args[:output]
+      FileUtils.mkdir_p(File.dirname(task_args[:output]))
+      File.write(task_args[:output], json)
+      puts "Permittable: wrote #{task_args[:output]} " \
+           "(#{controllers.length} controller#{'s' unless controllers.length == 1})"
+    else
+      puts json
+    end
+  end
+end

data/lib/permittable/version.rb

@@ -1,3 +1,3 @@
 module Permittable
-  VERSION = "0.2.0".freeze
+  VERSION = "0.3.0".freeze
 end

data/lib/permittable.rb

@@ -313,9 +313,9 @@ 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].freeze
-    NESTED_OPTS = %i[virtual sensitive message].freeze
-    ARRAY_OPTS  = %i[of length default validate virtual sensitive required transform message].freeze
+    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
 
     attr_reader :finalizer
 
@@ -368,7 +368,8 @@ module Permittable
       validate_length!(name, field[:length]) if field.key?(:length)
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
-      validate_array_default!(field) if field.key?(:default)
+      validate_array_authored_value!(field, :default) if field.key?(:default)
+      validate_array_authored_value!(field, :example) if field.key?(:example)
       validate_message!(field)
       @fields << field
     end
@@ -442,7 +443,8 @@ module Permittable
       validate_callable!(name, :validate, field[:validate]) if field.key?(:validate)
       validate_callable!(name, :transform, field[:transform]) if field.key?(:transform)
       resolve_normalizer!(field)
-      validate_default!(field)
+      validate_authored_value!(field, :default)
+      validate_authored_value!(field, :example)
       validate_message!(field)
     end
 
@@ -481,27 +483,28 @@ module Permittable
       end
     end
 
-    # A default must satisfy the field's own contract — catching a bad
-    # default at class load beats shipping it to every request.
-    def validate_default!(field)
-      return unless field.key?(:default)
+    # An authored value (`default:`, or a documentation `example:`) must
+    # satisfy the field's own contract — catching a lie at class load beats
+    # shipping it to every request (or publishing it in generated docs).
+    def validate_authored_value!(field, opt)
+      return unless field.key?(opt)
 
-      status, code = Coercion.check_scalar(field, field[:default])
+      status, code = Coercion.check_scalar(field, field[opt])
       return if status == :ok
 
-      raise ArgumentError, "#{LABEL}: :default for field :#{field[:name]} violates its own contract (#{code})"
+      raise ArgumentError, "#{LABEL}: :#{opt} for field :#{field[:name]} violates its own contract (#{code})"
     end
 
-    def validate_array_default!(field)
-      default = field[:default]
-      raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} must be an Array" unless default.is_a?(Array)
+    def validate_array_authored_value!(field, opt)
+      value = field[opt]
+      raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} must be an Array" unless value.is_a?(Array)
       return unless field[:of]
 
-      default.each do |element|
+      value.each do |element|
         status, code = Coercion.cast(field[:of], element)
         next if status == :ok
 
-        raise ArgumentError, "#{LABEL}: :default for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
+        raise ArgumentError, "#{LABEL}: :#{opt} for array :#{field[:name]} contains an element violating of: :#{field[:of]} (#{code})"
       end
     end
 
@@ -561,7 +564,9 @@ module Permittable
     #            undeclared keys, at every nesting level.
     #   enforce: false (default) validates lazily on the first
     #            permitted_params call; true validates in a before_action.
-    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, &block)
+    #   desc:    documentation only — carried on the rule for exporters
+    #            (Permittable::OpenAPI); the runtime never reads it.
+    def permit_params(*actions, root: false, model: nil, unknown: :ignore, enforce: false, desc: nil, &block)
       raise ArgumentError, "#{LABEL}: permit_params requires a block declaring the contract fields" unless block
 
       unknown = unknown.to_sym
@@ -577,7 +582,7 @@ module Permittable
 
       rule = { actions: actions.flatten.map(&:to_s).freeze, root: root && root.to_sym,
                model: model_class, unknown: unknown, enforce: !!enforce, fields: fields,
-               finalize: builder.finalizer }.freeze
+               finalize: builder.finalizer, desc: desc }.freeze
       self.permittable_contracts = permittable_contracts + [rule]
     end
 
@@ -873,5 +878,11 @@ module Permittable
   end
 end
 
-# Boot-time integration (filter_parameters registration), Rails apps only
+# Contract exporters — the other readers of the frozen contract registry.
+# Loaded after the module body so OpenAPI can see the concern's own methods.
+require "permittable/json_schema"
+require "permittable/open_api"
+
+# Boot-time integration (filter_parameters registration, the
+# permittable:openapi rake task), Rails apps only
 require "permittable/railtie" if defined?(Rails::Railtie)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: permittable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ethan Nguyen
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-18 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -50,7 +50,10 @@ files:
 - lib/permittable/column_guard.rb
 - lib/permittable/error_envelope.rb
 - lib/permittable/filter_parameter_registry.rb
+- lib/permittable/json_schema.rb
+- lib/permittable/open_api.rb
 - lib/permittable/railtie.rb
+- lib/permittable/tasks/openapi.rake
 - lib/permittable/version.rb
 homepage: https://github.com/VSN2015/permittable
 licenses: