How-to guides
v0.1.6
Each guide covers one task with GuardedStruct: nest structs with sub_field, accept more than one shape with conditional_field, fill and check fields from other fields, use virtual, dynamic and pattern-keyed fields, write validators and your own derive ops, validate input without building a struct, handle and translate errors, inspect and diff structs, use GuardedStruct in an Ash resource, and give a coding agent the rules.
Pick the guide for the job in front of you. The pages below show each one with a short summary.
- Nest structs with sub_field Declare nested structs inline with sub_field, build lists of them with structs: true, reuse other guarded modules, and read nested errors.
- Accept more than one shape with conditional_field Let one field accept several shapes with conditional_field: declare children, add validators and hints, accept lists, and read the errors.
- Fill and check fields from other fields Fill fields with auto, copy values with from, require other fields with on, and limit a field by another field's value with domain.
- Use virtual, dynamic and pattern-keyed fields Check a value without storing it with virtual_field, keep a map as sent with dynamic_field, and describe maps with no fixed keys.
- Write a field validator and a main validator Run your own Elixir code in the builder: a validator for one field and a main validator for the whole map, and when each one runs.
- Add your own derive ops Add your own validate and sanitize ops with a derive extension, register them per module or for the app, or use fallback modules.
- Validate input without building a struct Run GuardedStruct rules without building a struct: check one value with Validate.run, one field with Validate.field, or a subset with partial.
- Handle and translate errors Read the error list, filter it, flatten nested errors, raise an exception, wrap errors with Splode, and translate the messages.
- Inspect, diff and observe structs Look up fields with GuardedStruct.Info, compare structs with Diff, build a sample with example/0, and watch builds with telemetry events.
- Use GuardedStruct in an Ash resource Add the GuardedStruct.AshResource extension to an Ash resource so create and update actions sanitize and validate input, atomically too.
- Give your coding agent the GuardedStruct rules Sync GuardedStruct's usage rules and skills into AGENTS.md and .claude/skills with the usage_rules package, or copy the skills by hand.