Behaviour for custom codec modules.

A custom codec lets you override the default encode/decode/schema logic for specific types in your module. When spectra encounters a type defined in a codec module, it calls your callbacks first. Return {:ok, result} to provide a custom result, {:error, errors} when the data is invalid for a type your codec owns, or :continue to fall through to spectra's built-in structural encoding/decoding for types your codec does not handle.

Usage

Add use Spectral.Codec to your module and implement the required callbacks. Spectra detects codec modules by checking for @behaviour Spectral.Codec in the compiled BEAM, so no extra registration is needed:

defmodule MyGeoModule do
  use Spectral.Codec

  @opaque point :: {float(), float()}

  @impl Spectral.Codec
  def encode(_format, _caller_type_info, {:type, :point, 0}, _target_type, {x, y}, _config)
      when is_number(x) and is_number(y) do
    {:ok, [x, y]}
  end

  def encode(_format, _caller_type_info, {:type, :point, 0}, _target_type, data, _config) do
    {:error, [%Spectral.Error{type: :type_mismatch, location: [], context: %{type: {:type, :point, 0}, value: data}}]}
  end

  # Types not handled by this codec → continue to default
  def encode(_format, _caller_type_info, _type_ref, _target_type, _data, _config), do: :continue

  @impl Spectral.Codec
  def decode(_format, _caller_type_info, {:type, :point, 0}, _target_type, [x, y], _config)
      when is_number(x) and is_number(y) do
    {:ok, {x, y}}
  end

  def decode(_format, _caller_type_info, {:type, :point, 0}, _target_type, data, _config) do
    {:error, [%Spectral.Error{type: :type_mismatch, location: [], context: %{type: {:type, :point, 0}, value: data}}]}
  end

  def decode(_format, _caller_type_info, _type_ref, _target_type, _input, _config), do: :continue

  @impl Spectral.Codec
  def schema(:json_schema, _caller_type_info, {:type, :point, 0}, _target_type, _config) do
    %{type: "array", items: %{type: "number"}, minItems: 2, maxItems: 2}
  end
end

The target_type argument

The fourth argument to encode/6, decode/6, and schema/5 is the sp_type() instantiation node from the type traversal. For generic types (those with type variables, such as MapSet.t(elem)) this is the reference node and carries the concrete type-variable bindings of the current instantiation. Use Spectral.Type.type_args/1 to extract them for recursive encoding/decoding.

For non-generic types this argument is the resolved type definition and Spectral.Type.type_args/1 returns [].

Return Values

• {:ok, result} — Use this result instead of the default
• {:error, errors} — The data is invalid for a type this codec handles; errors is a list of %Spectral.Error{} structs
• :continue — This codec does not handle this type; fall through to spectra's built-in structural codec

The distinction between {:error, ...} and :continue matters: return {:error, ...} when the data has the wrong shape for a type your codec owns, and :continue for type references your codec does not recognise at all.

Recursive Calls

When your codec handles a container type and needs to encode or decode its elements according to their types, use the helper functions on this module rather than calling Spectral.encode/5 or Spectral.decode/5. The helpers preserve the runtime config (cache mode, codec registry, format) across the traversal; the public Spectral API would start a fresh traversal and lose that context.

@impl Spectral.Codec
def encode(format, caller_type_info, {:type, :wrapper, 1}, target_type, %Wrapper{value: v}, config) do
  case Spectral.Type.type_args(target_type) do
    [elem_type] ->
      case Spectral.Codec.encode(format, caller_type_info, elem_type, v, config) do
        {:ok, encoded} -> {:ok, %{"value" => encoded}}
        error -> error
      end
    [] -> {:ok, %{"value" => v}}
  end
end

Use Spectral.Type.type_args/1 to extract the concrete type arguments from target_type when handling generic types (see the target_type section above).

Global Codec Registry

To use a codec for types defined in a different module (e.g., a stdlib or third-party type you cannot annotate), register it via the application environment:

Application.put_env(:spectra, :codecs, %{
  {DateTime, {:type, :t, 0}} => Spectral.Codec.DateTime
})