Error shapes and actions
v0.1.4
Every failure in GuardedStruct is a map inside a list: {:error, [map, ...]}. This page lists the shapes those maps take and every action that is not the name of a derive op. For the actions of derive ops, see Validate ops.
Shapes
| Shape | Keys | Produced by |
|---|---|---|
| Field error | field, action, message | Every check on one field. |
| Nested error | field, errors | A failed sub_field, struct: or structs: value. errors holds the inner error maps. The map has no action. |
| Conditional error | field, action (conditionals), errors | A conditional_field where no child accepted the value. |
A field error can carry extra keys.
| Key | Present when |
|---|---|
__hint__ | The error comes from a child of a conditional field that has a hint:. |
__index__ | The error comes from a list item checked by each. It holds the zero-based position. |
field_path | The action is domain_parameters. It holds the path that failed. |
key | The error comes from a pattern-keyed map. It holds the key. |
Actions
| Action | Meaning | Field | Default message |
|---|---|---|---|
required_fields | A key in enforce_keys is missing. One error per missing key. | The key. | Please submit required fields. |
authorized_fields | The input has a key that is not a field, and authorized_fields: true is set. One error per key. | The key. | Unauthorized keys are present in the sent data. |
bad_parameters | The input is not a map or one of the accepted tuples, a conditional child cannot build a non-map, or Validate.run/2 got a derive string it cannot read or with a wrong operand. In that last case the field is :__value__ and the message names the problem. | :__root__ | Your input must be a map or list of maps |
dependent_keys | An on: path has no value. | The field with on:. | The required dependency for field <field> has not been submitted. and, on a second line, You must have field <last key of the path> in your input. |
domain_parameters | A domain: rule failed. | The field with domain:. | Based on field <field> input you have to send authorized data, or the same text ending in and required key when a required path is missing. |
validator | A validator: function or validator/2 returned {:error, field, message}. | The field. | Your message. |
conditionals | No child of a conditional field accepted the value. | The conditional field. | No message. The inner errors carry theirs. |
type | An op name is not defined, or an op got a kind of value it does not handle. | The field. | Unexpected type error in <field> field |
each | each=[...] got a value that is not a list. | The field. | One or more items in the <field> field failed validation |
either | No inner op of either=[...] passed. | The field. | None of the conditions for checking the <field> field is not correct |
custom | A custom=[Module, function] function did not return true. | The field. | The condition for checking the <field> field is not correct |
key_pattern | A key of a pattern-keyed map matches no pattern. | :__map__ | key "<key>" does not match any declared pattern |
unknown_field | Validate.field/3,4 got a name that is not a field. | The name. | field :<name> is not defined on <Module> |
The messages of key_pattern and unknown_field, the input must be a map message of Validate.partial/2, and the bad_parameters message of Validate.run/2, are fixed English text. The other messages come from GuardedStruct.Messages and can be replaced, as Handle and translate errors shows.
Fields
:__root__is the field of an error that is not about one field, such asbad_parameters.:__value__is the field name used byValidate.run/2, because it has no module to take a name from.:__map__is the field of errors about a whole pattern-keyed map, such askey_patternand avalidator:error of a pattern field.
Order
- Checks that run before nested values are built stop the build, and only their errors come back. See How the builder works.
- When several ops of one field fail, there is one error per op, with the last op first.
- The order of errors that belong to different fields is not defined.