dexkit 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41c8e4455fb4a4cca73b1d12da366b53bdbbada2cbae773917a12d344a150dd4
-  data.tar.gz: 86c4e76004df8b968c094b7b252a988eafe2f7aee035505ddb7bbeae1f25e04a
+  metadata.gz: 493f1873cf71e1f8e2348f4f15e3e508962d9ae310b85f7b4aac8a756396de05
+  data.tar.gz: ad50fd8349a45e4c4bc536f68bb2c74ee10b59e8b80856fca2823bb9f9a998cf
 SHA512:
-  metadata.gz: 89a9f6075f3955300dbe3944a9adc9b80ab56c3b4dc60d9458ea370f68c5c83ab5b3f2daad26c6f852d6f423a498ccf068914853e9866c05442765539ac6ac91
-  data.tar.gz: cd541ee35700cf9aa877b3630d66f0b9580263d0fddc7f381200afe32c638f832d941112387f646fa59500c26bb552461ad5bf0f0ec79dcf7bb97d76ebcbfb86
+  metadata.gz: 18ca385b0d66155e35c3f08164d3b558e85f3f29a586b492d664c72c24f746e6e70c0d6692faedb348e7c849096eb0f3ddfd98a5515e2de5b5ce05084cab3d5e
+  data.tar.gz: 2e7c2e59443b2dff7fb3a9de4c3296ce1b71c4f870bf47d2ce503f5d5c23105a1cee5549618451741a21fb6d0c8fcb0eba53b94d4edcf8e999e1164e9eabf96f

data/CHANGELOG.md

@@ -1,12 +1,34 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-03-09
+
+### Added
+
+- **`field` / `field?` DSL for forms** – `field :name, :string` declares a required field with auto-presence validation; unconditional explicit presence validators deduplicate with it, while scoped/conditional validators still layer on top. `field? :notes, :string` declares an optional field (nil by default). Both support `desc:` for metadata and `default:` for defaults. Raw `attribute` remains available as an escape hatch
+- **Form registry and description** – `Dex::Form` now extends `Registry`, giving forms `description`, `Dex::Form.registry`, and `deregister` – the same ecosystem as Operation, Event, and Handler
+- **Form ambient context** – forms support the same `context` DSL as Operation and Event. `context :locale` auto-fills from `Dex.context` during initialization. Uses the same shared `ContextDSL` module with Form-specific injection
+- **Form export** – `Form.to_h` (class-level schema), `Form.to_json_schema`, and `Dex::Form.export(format:)` for bulk export. Nested forms are recursively included in both formats, and bulk export returns top-level named forms without listing nested helper classes separately
+- **Query registry, description, context, and export** – `Dex::Query` now extends `Registry` (giving `description`, `Dex::Query.registry`, `deregister`), includes `ContextSetup` (enabling `context :tenant` to auto-fill from `Dex.with_context`), and adds `Query.to_h`, `Query.to_json_schema`, `Dex::Query.export(format:)`. Query is now a full citizen alongside Operation, Event, and Form
+
+### Changed
+
+- **Shared context DSL** – extracted `Dex::ContextDSL` as a shared module used by both `ContextSetup` (Operation/Event) and `Form::Context`. No behavior change for Operation or Event
+
 ## [0.9.0] - 2026-03-09
 
 ### Breaking
 
+- **Unified execution tracing replaces event-only tracing** – `Dex::Trace` is a new fiber-local trace that spans operations, events, and handlers. Operations get `op_...` execution IDs, events get `ev_...` IDs (replacing UUIDs), handlers get `hd_...` IDs, and traces are correlated with `tr_...` IDs. `event.trace { }` is removed – use `caused_by:` for explicit event causality and `Dex::Trace.start(actor:)` at request/job boundaries. `Dex::Event::Trace` remains as a thin delegation layer
+- **Operation record primary keys are now string IDs** – records use the operation's `op_...` execution ID as a string primary key instead of auto-increment integers. The recording schema adds `trace_id`, `actor_type`, `actor_id`, and `trace` columns. Existing tables need a migration to adopt the new schema
 - **Mongoid transaction support removed** — `transaction :mongoid` and `config.transaction_adapter = :mongoid` are no longer valid. Dex no longer ships a Mongoid transaction adapter. Before: Mongoid transactions could be enabled via configuration or per-operation DSL. After: both forms raise `ArgumentError` immediately at declaration/configuration time. Mongoid-only apps continue to work — transactions are automatically disabled (no adapter detected), and `after_commit` fires immediately after success. If you need Mongoid multi-document transactions, call `Mongoid.transaction` directly inside `perform`
 - **Recording backends now validate required attributes before use** — Dex no longer silently drops missing `params`, `result`, `status`, or `once` attributes from `record_class`. Before: partial ActiveRecord/Mongoid recording models could appear to work while losing status transitions, replay data, or async params. After: Dex raises `ArgumentError` naming the missing attributes required by core recording, async record jobs, or `once`. Apps using minimal recording models must add the required columns/fields or explicitly disable the features that need them
 
+### Added
+
+- **`Dex::Trace` API** – `start(actor:, trace_id:)`, `.trace_id`, `.current`, `.current_id`, `.actor`, `.to_s`, `.dump`, `.restore`. Fiber-local, auto-starts when no trace is active, serializes across async job boundaries
+- **Trace persistence** – operation records and event stores persist `id`, `trace_id`, `actor_type`, `actor_id`, and `trace` when the columns exist. Event metadata includes `event_ancestry` for materialized-path tree queries
+- **`Dex::Id`** – Stripe-style prefixed ID generation with embedded timestamps for sortability
+
 ### Fixed
 
 - **Mongoid-only Rails compatibility** — Dex boots and runs cleanly in Mongoid-only Rails apps without `activerecord` loaded, with prescriptive `LoadError`s for unsupported paths such as `advisory_lock` and async event dispatch without `ActiveJob`

data/README.md

@@ -73,6 +73,17 @@ end
 Order::Fulfill.new(order_id: 123).async(queue: "fulfillment").call
 ```
 
+**Execution tracing** – every operation gets a prefixed ID and joins a unified trace across operations, events, and handlers:
+
+```ruby
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  Order::Place.call(customer: 42, product: 7, quantity: 2)
+end
+
+Dex::Trace.trace_id   # => "tr_..."
+Dex::Trace.current    # => [{ type: :actor, ... }, { type: :operation, ... }]
+```
+
 **Idempotency** with `once` — run an operation at most once for a given key. Results are replayed on duplicates:
 
 ```ruby
@@ -210,11 +221,12 @@ Order::Placed.publish(order_id: 1, total: 99.99)
 
 **Async by default** — handlers dispatched via ActiveJob. `sync: true` for inline. If ActiveJob is not loaded, async publish raises `LoadError`.
 
-**Causality tracing** — link events in chains with shared `trace_id`:
+**Causality tracing** – events join the unified execution trace, and child events link to their cause:
 
 ```ruby
-order_placed.trace do
-  Shipment::Reserved.publish(order_id: 1)
+Dex::Trace.start(actor: { type: :user, id: 42 }) do
+  order_placed = Order::Placed.new(order_id: 1, total: 99.99)
+  Shipment::Reserved.publish(order_id: 1, caused_by: order_placed)
 end
 ```
 
@@ -241,25 +253,29 @@ end
 
 ## Forms
 
-Form objects with typed attributes, normalization, nested forms, and Rails form builder compatibility.
+Form objects with typed fields, normalization, nested forms, ambient context, JSON Schema export, and Rails form builder compatibility.
 
 ```ruby
 class Employee::Form < Dex::Form
+  description "Employee onboarding form"
   model Employee
 
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: true
-  validates :first_name, :last_name, presence: true
+  validates :email, uniqueness: true
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    validates :street, :city, presence: true
+    field :street, :string
+    field :city, :string
+    field? :apartment, :string
   end
 end
 
@@ -270,18 +286,21 @@ form.valid?
 
 ### What you get out of the box
 
-**ActiveModel attributes** with type casting, normalization, and full Rails validation DSL.
+**`field` / `field?`** — required and optional fields with auto-presence validation, `desc:` metadata, and defaults. Backed by ActiveModel attributes with type casting and normalization. Unconditional `validates :attr, presence: true` deduplicates with `field`; scoped validations still layer on top.
 
 **Nested forms** — `nested_one` and `nested_many` with automatic Hash coercion, `_destroy` support, and error propagation:
 
 ```ruby
 nested_many :emergency_contacts do
-  attribute :name, :string
-  attribute :phone, :string
-  validates :name, :phone, presence: true
+  field :name, :string
+  field :phone, :string
 end
 ```
 
+**Ambient context** — auto-fill fields from `Dex.context`, same DSL as Operation and Event.
+
+**Registry & Export** — `description`, `to_json_schema`, class-level `to_h`, and `Dex::Form.export` for schema introspection. Nested form schemas recurse in both export formats, and bulk export includes only top-level named forms.
+
 **Rails form compatibility** — works with `form_with`, `fields_for`, and nested attributes out of the box.
 
 **Uniqueness validation** against the database, with scope, case-sensitivity, and current-record exclusion.
@@ -305,11 +324,16 @@ Declarative query objects for filtering and sorting ActiveRecord and Mongoid sco
 
 ```ruby
 class Order::Query < Dex::Query
+  description "Search orders"
+
   scope { Order.all }
 
   prop? :status, String
   prop? :customer, _Ref(Customer)
   prop? :total_min, Integer
+  prop? :tenant, String
+
+  context tenant: :current_tenant
 
   filter :status
   filter :customer
@@ -323,6 +347,10 @@ orders = Order::Query.call(status: "pending", sort: "-total")
 
 ### What you get out of the box
 
+**Registry, description, and context** — same ecosystem as Operation, Event, and Form. `Dex::Query.registry` discovers all query classes, `description` documents intent, and `context` auto-fills props from `Dex.with_context`.
+
+**Export** — `Query.to_h`, `Query.to_json_schema`, `Dex::Query.export(format:)` for introspection and bulk export.
+
 **11 built-in filter strategies** — `:eq`, `:not_eq`, `:contains`, `:starts_with`, `:ends_with`, `:gt`, `:gte`, `:lt`, `:lte`, `:in`, `:not_in`. Custom blocks for complex logic.
 
 **Sorting** with ascending/descending column sorts, custom sort blocks, and defaults.

data/gemfiles/mongoid_no_ar.gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ..
   specs:
-    dexkit (0.8.0)
+    dexkit (0.10.0)
       activemodel (>= 6.1)
       literal (~> 1.9)
       zeitwerk (~> 2.6)
@@ -180,7 +180,7 @@ CHECKSUMS
   connection_pool (3.0.2) sha256=33fff5ba71a12d2aa26cb72b1db8bba2a1a01823559fb01d29eb74c286e62e0a
   crass (1.0.6) sha256=dc516022a56e7b3b156099abc81b6d2b08ea1ed12676ac7a5657617f012bd45d
   date (3.5.1) sha256=750d06384d7b9c15d562c76291407d89e368dda4d4fff957eb94962d325a0dc0
-  dexkit (0.8.0)
+  dexkit (0.10.0)
   drb (2.2.3) sha256=0b00d6fdb50995fe4a45dea13663493c841112e4068656854646f418fda13373
   erb (6.0.2) sha256=9fe6264d44f79422c87490a1558479bd0e7dad4dd0e317656e67ea3077b5242b
   erubi (1.13.1) sha256=a082103b0885dbc5ecf1172fede897f9ebdb745a4b97a5e8dc63953db1ee4ad9

data/guides/llm/EVENT.md

@@ -30,9 +30,9 @@ class UserCreated < Dex::Event
 end
 ```
 
-Reserved names: `id`, `timestamp`, `trace_id`, `caused_by_id`, `caused_by`, `context`, `publish`, `metadata`, `sync`.
+Reserved names: `id`, `timestamp`, `trace_id`, `caused_by_id`, `caused_by`, `event_ancestry`, `context`, `publish`, `metadata`, `sync`.
 
-Events are frozen after creation. Each gets auto-generated `id` (UUID), `timestamp` (UTC), `trace_id`, and optional `caused_by_id`.
+Events are frozen after creation. Each gets auto-generated `id` (`ev_...`), `timestamp` (UTC), `trace_id` (`tr_...` by default), optional `caused_by_id`, and `event_ancestry` (ordered ancestor event IDs).
 
 ### Literal Types Cheatsheet
 
@@ -72,10 +72,11 @@ class NotifyWarehouse < Dex::Event::Handler
   def perform
     event                    # accessor — the event instance
     event.order_id           # typed props
-    event.id                 # UUID
+    event.id                 # prefixed event ID (ev_...)
     event.timestamp          # Time (UTC)
     event.caused_by_id       # parent event ID (if traced)
-    event.trace_id           # shared trace ID across causal chain
+    event.trace_id           # shared trace / correlation ID
+    event.event_ancestry     # ordered ancestor event IDs
   end
 end
 ```
@@ -179,22 +180,20 @@ Default handler pipeline: `[:transaction, :callback]`.
 
 ## Tracing (Causality)
 
-Link events in a causal chain. All events in a chain share the same `trace_id`.
+Events participate in the unified `Dex::Trace` used by operations and handlers. All events in a trace share the same `trace_id`.
 
 ```ruby
-order_placed = OrderPlaced.new(order_id: 1, total: 99.99)
-
-# Option 1: trace block
-order_placed.trace do
-  InventoryReserved.publish(order_id: 1)   # caused_by_id = order_placed.id
-  ShippingRequested.publish(order_id: 1)   # same trace_id
+# Start a trace at the request/job boundary
+Dex::Trace.start(actor: { type: :user, id: current_user.id }) do
+  OrderPlaced.publish(order_id: 1, total: 99.99)
 end
 
-# Option 2: caused_by keyword
+# Explicit event-to-event causality
+order_placed = OrderPlaced.new(order_id: 1, total: 99.99)
 InventoryReserved.publish(order_id: 1, caused_by: order_placed)
 ```
 
-Nesting works — each child gets the nearest parent's `id` as `caused_by_id`, and the root's `trace_id`.
+When an event is published inside a handler, the handler's event becomes the cause automatically. Explicit `caused_by:` sets `caused_by_id` and appends to `event_ancestry`.
 
 ---
 
@@ -218,12 +217,16 @@ Store events to database when configured:
 
 ```ruby
 Dex.configure do |c|
-  c.event_store = EventRecord   # any model with create!(event_type:, payload:, metadata:)
+  c.event_store = EventRecord   # Dex passes trace fields when the model supports them
 end
 ```
 
 ```ruby
-create_table :event_records do |t|
+create_table :event_records, id: :string do |t|
+  t.string :trace_id
+  t.string :actor_type
+  t.string :actor_id
+  t.jsonb  :trace
   t.string :event_type
   t.jsonb  :payload
   t.jsonb  :metadata
@@ -238,6 +241,11 @@ class EventRecord
   include Mongoid::Document
   include Mongoid::Timestamps
 
+  field :_id, type: String
+  field :trace_id, type: String
+  field :actor_type, type: String
+  field :actor_id, type: String
+  field :trace, type: Array
   field :event_type, type: String
   field :payload, type: Hash
   field :metadata, type: Hash
@@ -381,10 +389,7 @@ class CreateOrderTest < Minitest::Test
   def test_trace_chain
     capture_events do
       parent = OrderPlaced.new(order_id: 1, total: 99.99)
-
-      parent.trace do
-        InventoryReserved.publish(order_id: 1)
-      end
+      InventoryReserved.publish(order_id: 1, caused_by: parent)
 
       child = _dex_published_events.last
       assert_event_trace(parent, child)

data/guides/llm/FORM.md

@@ -10,58 +10,80 @@ All examples below build on this form unless noted otherwise:
 
 ```ruby
 class OnboardingForm < Dex::Form
+  description "Employee onboarding"
   model User
 
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :start_date, :date
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :start_date, :date
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: true
-  validates :first_name, :last_name, :department, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: true
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 end
 ```
 
 ---
 
-## Defining Forms
+## Declaring Fields
 
-Forms use ActiveModel under the hood. Attributes are declared with `attribute` (same as ActiveModel::Attributes).
+### `field` — required
+
+Declares a required field. Auto-adds presence validation. Unconditional `validates :attr, presence: true` deduplicates with it; scoped or conditional presence validators do not make the field optional outside those cases.
 
 ```ruby
-class ProfileForm < Dex::Form
-  attribute :name, :string
-  attribute :age, :integer
-  attribute :bio, :string
-  attribute :active, :boolean, default: true
-  attribute :born_on, :date
-end
+field :name, :string
+field :email, :string, desc: "Work email"
+field :currency, :string, default: "USD"
+```
+
+### `field?` — optional
+
+Declares an optional field. Defaults to `nil` unless overridden.
+
+```ruby
+field? :notes, :string
+field? :priority, :integer, default: 0
 ```
 
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `desc:` | Human-readable description (for introspection and JSON Schema) |
+| `default:` | Default value (forwarded to ActiveModel) |
+
 ### Available types
 
 `:string`, `:integer`, `:float`, `:decimal`, `:boolean`, `:date`, `:datetime`, `:time`.
 
+### `attribute` escape hatch
+
+Raw ActiveModel `attribute` is still available. Not tracked in field registry, no auto-presence, not in exports.
+
+### Boolean fields
+
+`field :active, :boolean` checks for `nil` (not `blank?`), so `false` is valid.
+
 ### `model(klass)`
 
 Declares the backing model class. Used by:
@@ -93,11 +115,11 @@ normalizes :name, :email, with: -> { _1&.strip.presence }   # multiple attrs
 
 ## Validation
 
-Full ActiveModel validation DSL:
+Full ActiveModel validation DSL. Required fields auto-validate presence — no need to add `validates :name, presence: true` when using `field :name, :string`.
 
 ```ruby
-validates :email, presence: true, format: { with: URI::MailTo::EMAIL_REGEXP }
-validates :name, presence: true, length: { minimum: 2, maximum: 100 }
+validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+validates :name, length: { minimum: 2, maximum: 100 }
 validates :role, inclusion: { in: %w[admin user] }
 validates :email, uniqueness: true                    # checks database
 validate :custom_validation_method
@@ -111,6 +133,15 @@ form.errors[:email]      # => ["can't be blank"]
 form.errors.full_messages # => ["Email can't be blank"]
 ```
 
+### Contextual requirements
+
+Use `field?` with an explicit validation context:
+
+```ruby
+field? :published_at, :datetime
+validates :published_at, presence: true, on: :publish
+```
+
 ### ValidationError
 
 ```ruby
@@ -121,6 +152,94 @@ error.form     # => the form instance
 
 ---
 
+## Ambient Context
+
+Auto-fill fields from `Dex.context` – same DSL as Operation and Event:
+
+```ruby
+class Order::Form < Dex::Form
+  field :locale, :string
+  field :currency, :string
+
+  context :locale                       # shorthand: field name = context key
+  context currency: :default_currency   # explicit: field name → context key
+end
+
+Dex.with_context(locale: "en", default_currency: "USD") do
+  form = Order::Form.new
+  form.locale    # => "en"
+  form.currency  # => "USD"
+end
+```
+
+Explicit values always win. Context references must point to declared fields or attributes.
+
+---
+
+## Registry & Export
+
+### Description
+
+```ruby
+class OnboardingForm < Dex::Form
+  description "Employee onboarding"
+end
+
+OnboardingForm.description  # => "Employee onboarding"
+```
+
+### Registry
+
+```ruby
+Dex::Form.registry  # => #<Set: {OnboardingForm, ...}>
+```
+
+### Class-level `to_h`
+
+```ruby
+OnboardingForm.to_h
+# => {
+#   name: "OnboardingForm",
+#   description: "Employee onboarding",
+#   fields: {
+#     first_name: { type: :string, required: true },
+#     email: { type: :string, required: true },
+#     notes: { type: :string, required: false },
+#     ...
+#   },
+#   nested: {
+#     address: { type: :one, fields: { ... }, nested: { ... } },
+#     documents: { type: :many, fields: { ... } }
+#   }
+# }
+```
+
+### `to_json_schema`
+
+```ruby
+OnboardingForm.to_json_schema
+# => {
+#   "$schema": "https://json-schema.org/draft/2020-12/schema",
+#   type: "object",
+#   title: "OnboardingForm",
+#   description: "Employee onboarding",
+#   properties: { email: { type: "string" }, ... },
+#   required: ["first_name", "last_name", "email", ...],
+#   additionalProperties: false
+# }
+```
+
+### Global export
+
+```ruby
+Dex::Form.export(format: :json_schema)
+# => [{ ... OnboardingForm schema ... }, ...]
+```
+
+Bulk export returns top-level named forms only. Nested helper classes generated by `nested_one` and `nested_many` stay embedded in their parent export instead of appearing as separate entries.
+
+---
+
 ## Nested Forms
 
 ### `nested_one`
@@ -129,9 +248,9 @@ One-to-one nested form. Automatically coerces Hash input.
 
 ```ruby
 nested_one :address do
-  attribute :street, :string
-  attribute :city, :string
-  validates :street, :city, presence: true
+  field :street, :string
+  field :city, :string
+  field? :apartment, :string
 end
 ```
 
@@ -152,9 +271,8 @@ One-to-many nested form. Handles Array, Rails numbered Hash, and `_destroy`.
 
 ```ruby
 nested_many :documents do
-  attribute :document_type, :string
-  attribute :document_number, :string
-  validates :document_type, :document_number, presence: true
+  field :document_type, :string
+  field :document_number, :string
 end
 ```
 
@@ -190,7 +308,7 @@ Override the auto-generated constant name:
 
 ```ruby
 nested_one :address, class_name: "HomeAddress" do
-  attribute :street, :string
+  field :street, :string
 end
 # Creates MyForm::HomeAddress instead of MyForm::Address
 ```
@@ -306,7 +424,7 @@ form.to_hash  # alias for to_h
 
 ### Controller pattern
 
-Strong parameters (`permit`) are not required — the form's attribute declarations are the whitelist. Just `require` the top-level key:
+Strong parameters (`permit`) are not required — the form's field declarations are the whitelist. Just `require` the top-level key:
 
 ```ruby
 class OnboardingController < ApplicationController
@@ -405,33 +523,34 @@ A form spanning User, Employee, and Address — the core reason form objects exi
 
 ```ruby
 class OnboardingForm < Dex::Form
-  attribute :first_name, :string
-  attribute :last_name, :string
-  attribute :email, :string
-  attribute :department, :string
-  attribute :position, :string
-  attribute :start_date, :date
+  description "Employee onboarding"
+
+  field :first_name, :string
+  field :last_name, :string
+  field :email, :string
+  field :department, :string
+  field :position, :string
+  field :start_date, :date
+  field :locale, :string
+  field? :notes, :string
+
+  context :locale
 
   normalizes :email, with: -> { _1&.strip&.downcase.presence }
 
-  validates :email, presence: true, uniqueness: { model: User }
-  validates :first_name, :last_name, :department, :position, presence: true
-  validates :start_date, presence: true
+  validates :email, uniqueness: { model: User }
 
   nested_one :address do
-    attribute :street, :string
-    attribute :city, :string
-    attribute :postal_code, :string
-    attribute :country, :string
-
-    validates :street, :city, :country, presence: true
+    field :street, :string
+    field :city, :string
+    field :postal_code, :string
+    field :country, :string
+    field? :apartment, :string
   end
 
   nested_many :documents do
-    attribute :document_type, :string
-    attribute :document_number, :string
-
-    validates :document_type, :document_number, presence: true
+    field :document_type, :string
+    field :document_number, :string
   end
 
   def self.for(user)
@@ -484,23 +603,38 @@ Forms are standard ActiveModel objects. Test them with plain Minitest — no spe
 
 ```ruby
 class OnboardingFormTest < Minitest::Test
-  def test_validates_required_fields
+  def test_required_fields_validated
     form = OnboardingForm.new
     assert form.invalid?
     assert form.errors[:email].any?
     assert form.errors[:first_name].any?
   end
 
+  def test_optional_fields_allowed_blank
+    form = OnboardingForm.new(
+      first_name: "Alice", last_name: "Smith",
+      email: "alice@example.com", department: "Eng",
+      position: "Dev", start_date: Date.today, locale: "en"
+    )
+    assert form.valid?
+    assert_nil form.notes
+  end
+
   def test_normalizes_email
     form = OnboardingForm.new(email: "  ALICE@EXAMPLE.COM  ")
     assert_equal "alice@example.com", form.email
   end
 
+  def test_context_fills_locale
+    form = Dex.with_context(locale: "en") { OnboardingForm.new }
+    assert_equal "en", form.locale
+  end
+
   def test_nested_validation_propagation
     form = OnboardingForm.new(
       first_name: "Alice", last_name: "Smith",
       email: "alice@example.com", department: "Eng",
-      position: "Developer", start_date: Date.today,
+      position: "Developer", start_date: Date.today, locale: "en",
       address: { street: "", city: "", country: "" }
     )
     assert form.invalid?
@@ -516,5 +650,12 @@ class OnboardingFormTest < Minitest::Test
     assert_equal "Alice", h[:first_name]
     assert_equal "123 Main", h[:address][:street]
   end
+
+  def test_json_schema_export
+    schema = OnboardingForm.to_json_schema
+    assert_equal "object", schema[:type]
+    assert_includes schema[:required], "first_name"
+    refute_includes schema[:required], "notes"
+  end
 end
 ```