Formata.Error exception (formata v0.1.0)

Copy Markdown View Source

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.

Summary

Types

kind()
location()
path()
t()

Functions

error(kind, code, message, fields \\ [])

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

format_path(path)

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

new(kind, code, message, fields \\ [])

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

Types

kind()

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

location()

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

path()

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

t()

@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
}

Functions

error(kind, code, message, fields \\ [])

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

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

format_path(path)

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

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

new(kind, code, message, fields \\ [])

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

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