GuardedStruct DSL — field, sub_field, conditional_field, virtual_field, dynamic_field

Every entity lives inside one guardedstruct do … end block.

field name, type, opts

field :email, :string,
  enforce: true,
  default: nil,
  derives: "sanitize(trim, downcase) validate(string, not_empty, email_r)",
  validator: {MyApp.Checks, :no_disposable_email},
  auto: {Ecto.UUID, :generate},
  from: "headers::auth_user_id",
  on: "profile::owner_id",
  hint: "primary-email"

sub_field name, type, opts do … end

Defines a nested submodule (e.g. MyApp.User.Profile) generated at compile time. Same options as field plus:

• error: true — generates a per-level Error exception.
• authorized_fields: true — reject keys not declared in this sub_field.
• main_validator: {Mod, :fn} — runs after every nested field validates.

Children: nested field, sub_field, conditional_field.

conditional_field name, type, opts do … end

Pick one child based on the input value. Children share the parent's name. Each child is tried in order; the first whose validator: returns {:ok, ...} wins. Use priority: true on at most one child to short-circuit.

• structs: true on the conditional — iterate a list, apply children per element.

• Aggregated error shape (on no match):

  %{field: name, action: :conditionals, errors: [child_attempt_errors...]}

  Each inner errors entry follows the canonical error shape.

virtual_field name, type, opts

Same surface as field, but the value is dropped from the final struct. Useful for password_confirmation-style inputs consumed by main_validator but not persisted. Schema accepts name, type, enforce, default, derives (+ legacy derive), validator, auto, from, on, domain, hint. Does not accept struct, structs, or priority.

dynamic_field name, opts

Free-form map slot. The inner map is identity-preserved — keys are not atomized at any depth. Used for attacker-controlled metadata where atom-table growth would be a DoS risk. Schema accepts the same options as virtual_field (no struct / structs / priority).

Defaults baked into the entity schema:

• type → map()
• default → %{}
• derives → "validate(map)"

The entity also auto-sets __dynamic__: true (internal flag — drives the :dynamic_field kind in __fields__/0 and tells Parser.convert_to_atom_map to leave inner values untouched).

@derives "..." / @derive_rules "..." decorators

Module attributes consumed by the next entity declaration. One-shot — the attribute is cleared after the consuming entity, like @doc. Useful for keeping fields short:

@derives "sanitize(trim, downcase) validate(string, not_empty, email_r)"
field :email, :string, enforce: true

@derives "sanitize(trim) validate(string, max_len=24)"
field :nickname, :string

Available on field, sub_field, conditional_field, virtual_field, dynamic_field.

Section options — guardedstruct opts do … end

guardedstruct enforce: true, authorized_fields: true, json: true do
  ...
end

Pattern-keyed maps

A field whose name: is a regex makes the module a pattern map — its builder/1 returns a plain map keyed by matching string keys, no defstruct. Use for shard tables, dynamic configuration.

What gets generated

Every guarded module gains at compile time:

• defstruct, @enforce_keys, @type t() / @opaque t(),
• keys/0,1, enforce_keys/0,1, example/0,
• __information__/0, __fields__/0, __field_meta__/1,
• __guarded_information__/0, __guarded_fields__/0, __guarded_field_meta__/1 (Ash-compatible aliases),
• builder/1,2,
• compile-time flags: __guarded_has_validator__/0, __guarded_has_main_validator__/0, __guarded_error_module__/0, __guarded_derive_extensions_opt__/0,
• sub_field submodules with the same surface.