# `Formata.Error`
[🔗](https://github.com/gsmlg-dev/formata/blob/v0.1.0/lib/formata/error.ex#L1)

Structured error returned by every Formata operation.

Expected failures are returned as `{:error, errors}` where `errors` is a
non-empty list of `%Formata.Error{}` values.

## Fields

  * `:kind` - the failure class, one of:
    * `:parse` - a document could not be decoded
    * `:encode` - data could not be written in the target format
    * `:schema` - a schema definition is invalid or cannot be compiled/resolved
    * `:validation` - data does not satisfy a schema
    * `:transform` - an explicit transformation (`cast/3`, `Formata.Transform`) failed
    * `:unsupported` - the requested operation or option is not supported for
      this schema, format, or value
  * `:code` - a stable machine-readable atom (for example `:syntax`,
    `:duplicate_key`, `:unrepresentable`, `:type`, `:required`,
    `:unknown_field`, `:oneOf`). Validation codes are taken from the backend
    (`Formata.Backplane.Schema.Error.code` for native schemas,
    `Formata.Backplane.JsonSchema.Types.Error.rule` for JSON Schema).
  * `:message` - a human-readable message.
  * `:backend` - the module that produced or detected the failure
    (`Formata.Jason`, `Formata.Toml`, `Formata.YamlElixir`, `Formata.Ymlr`, `Formata.Backplane.Schema`,
    `Formata.Backplane.JsonSchema`, or a Formata module for checks Formata performs).
  * `:format` - the codec format (`:json`, `:toml`, `:yaml`) when relevant.
  * `:path` - the data path as a list of map keys and list indexes
    (`[]` is the root).
  * `:schema_path` - the schema location when it is known.
  * `:location` - `%{line: pos_integer, column: pos_integer}` and/or
    `%{offset: non_neg_integer}` only when the backend supplies them;
    otherwise `nil`. Formata never invents source positions.
  * `:details` - extra structured data (expected values, keywords, ...).
  * `:cause` - the original backend error term, when useful.

# `kind`

```elixir
@type kind() :: :parse | :encode | :schema | :validation | :transform | :unsupported
```

# `location`

```elixir
@type location() ::
  nil
  | %{
      optional(:line) => pos_integer(),
      optional(:column) => pos_integer(),
      optional(:offset) => non_neg_integer()
    }
```

# `path`

```elixir
@type path() :: [term()]
```

# `t`

```elixir
@type t() :: %Formata.Error{
  __exception__: term(),
  backend: module() | nil,
  cause: term(),
  code: atom(),
  details: map(),
  format: atom() | nil,
  kind: kind(),
  location: location(),
  message: String.t(),
  path: path(),
  schema_path: path() | nil
}
```

# `error`

```elixir
@spec error(kind(), atom(), String.t(), keyword()) :: {:error, [t(), ...]}
```

Wraps a single error as the `{:error, [error]}` result shape.

# `format_path`

```elixir
@spec format_path(path()) :: String.t()
```

Formats a data path as a JSON-Pointer-like string, for example `/users/0/name`.

# `new`

```elixir
@spec new(kind(), atom(), String.t(), keyword()) :: t()
```

Builds an error. `kind`, `code`, and `message` are required.

---

*Consult [api-reference.md](api-reference.md) for complete listing*