JSON for Elixir applications, Phoenix, and Plug.
# config/config.exs
config :phoenix, :json_library, Formata.JSON
# endpoint.ex
plug Plug.Parsers,
parsers: [:urlencoded, :multipart, :json],
json_decoder: Phoenix.json_library()It provides the functions Phoenix requires of a :json_library (the
raising, single-argument functions of Elixir's built-in JSON):
decode!/1, encode!/1, and encode_to_iodata!/1.
Decoding
decode/2 and decode!/2 use Formata's strict JSON decoder:
RFC 8259, string keys (never atoms), and duplicate object keys
rejected instead of silently keeping one value, so a request body or socket
message cannot carry two different values for one field. On invalid input,
decode!/2 raises the first Formata.Error (an exception), which
Plug.Parsers turns into a Plug.Parsers.ParseError (HTTP 400).
Options:
:commentsand:trailing_commas- the boolean:jsondecode options, bothfalseby default. For example,json_decoder: {Formata.JSON, :decode!, [[comments: true]]}.:floats-:native(default), or a one-argument function receiving the original fractional/exponent number token. For exact Decimal values usefloats: &Decimal.new/1with your application's Decimal dependency. No binary float conversion occurs; integers remain integers. Callback return values are used directly and callback exceptions propagate.:objects-:maps(default) or:ordered_objects, which returnsFormata.JSON.OrderedObjectat every object, including nested objects. Duplicate keys remain errors in both modes.
Unknown options, invalid values, and malformed keyword entries return
:unsupported / :invalid_option errors. floats: :decimals is not an
option; pass the conversion function instead. decode/2 returns
{:ok, data} or {:error, [Formata.Error.t()]}; decode!/2 raises the first
error. Syntax errors carry source locations; duplicate-key errors carry
the containing object's path and the key in details.
Encoding
encode!/2 and encode_to_iodata!/2 delegate to Elixir's built-in JSON,
so they accept what Phoenix and LiveView send: atom keys and values,
integer keys, Date/Time/DateTime values, and structs that implement
the JSON.Encoder protocol (@derive JSON.Encoder). This differs from
Formata.encode(data, :json), which accepts only the strict portable value
domain; use that for documents that other formats or schemas must agree
with.
Both accept pretty: true for two-space indentation (default false),
including ordered objects nested in ordinary Elixir values. Invalid
options raise Formata.Error; unsupported values retain Elixir JSON's
encoding exceptions. The portable Formata.encode/3 and Formata.decode/3
retain their strict value domain and options.
Summary
Functions
Decodes JSON, returning data or structured errors. See the module options.
Decodes JSON strictly, raising Formata.Error on invalid input.
Encodes a term as a JSON binary with Elixir's JSON.
Encodes a term as JSON iodata with Elixir's JSON.
Functions
@spec decode(binary(), keyword()) :: Formata.Codec.result(term())
Decodes JSON, returning data or structured errors. See the module options.
iex> Formata.JSON.decode(~s({"a": 1}))
{:ok, %{"a" => 1}}
Decodes JSON strictly, raising Formata.Error on invalid input.
iex> Formata.JSON.decode!(~s({"a": [1, 2.5, null]}))
%{"a" => [1, 2.5, nil]}
iex> Formata.JSON.decode!(~s({"a": 1, "a": 2}))
** (Formata.Error) duplicate object key "a"
Encodes a term as a JSON binary with Elixir's JSON.
iex> Formata.JSON.encode!(%{status: :ok})
~s({"status":"ok"})
Encodes a term as JSON iodata with Elixir's JSON.
iex> Formata.JSON.encode_to_iodata!([1, "a"]) |> IO.iodata_to_binary()
~s([1,"a"])