Defines functions and the Normandy.Type behaviour for implementing basic custom types.

Normandy provides two types of custom types: basic types and parameterized types. Basic types are simple, requiring only four callbacks to be implemented, and are enough for most occasions. Parameterized types can be customized on the field definition and provide a wide variety of callbacks.

The definition of basic custom types and all of their callbacks are available in this module. You can learn more about parameterized types in Normandy.ParameterizedType. If in doubt, prefer to use basic custom types and rely on parameterized types if you need the extra functionality.

External vs internal vs serialized representation

The core functionality of a custom type is the mapping between external, internal and serialized representations of a value belonging to the type.

External data comes from the model's JSON or from caller params, internal data is the application's runtime representation, and serialized data is the form dump/1 returns: a term the JSON adapter can encode. Normandy calls dump/1 to check a field's :default when the schema compiles.

stateDiagram-v2
  external: External Data
  internal: Internal Data
  serialized: Serialized Data
  external --> internal: cast/1
  external --> serialized: dump/1
  internal --> serialized: dump/1

Example

Imagine you want to store a URI struct as part of a schema. A custom type is needed to handle the conversion between string input and the URI struct at runtime.

The custom type needs to handle the conversion from external data to runtime data (cast/1) as well as transforming that runtime data into a serializable format (dump/1).

defmodule URIType do
  use Normandy.Type
  def type, do: :map

  # Provide custom casting rules.
  # Cast strings into the URI struct to be used at runtime
  def cast(uri) when is_binary(uri) do
    {:ok, URI.parse(uri)}
  end

  # Accept casting of URI structs as well
  def cast(%URI{} = uri), do: {:ok, uri}

  # Everything else is a failure though
  def cast(_), do: :error

  # When dumping data, we *expect* a URI struct
  # but any value could be inserted into the schema struct at runtime,
  # so we need to guard against them.
  def dump(%URI{} = uri), do: {:ok, Map.from_struct(uri)}
  def dump(_), do: :error
end

Now we can use our new field type in our schemas:

defmodule UrlSchema do
  use Normandy.Schema

  schema do
    field :original_url, URIType
  end
end

Note: nil values are always bypassed and cannot be handled by custom types.

Custom types with validation

Custom types can also include validation logic. For example, an encoded ID type that handles base64 encoding:

defmodule EncodedId do
  use Normandy.Type

  def type, do: :string

  def cast(id) when is_integer(id) do
    {:ok, encode_id(id)}
  end
  def cast(id) when is_binary(id) do
    case Base.decode64(id) do
      {:ok, _} -> {:ok, id}
      :error -> :error
    end
  end
  def cast(_), do: :error

  def dump(id) when is_binary(id) do
    case Base.decode64(id) do
      {:ok, decoded} -> {:ok, String.to_integer(decoded)}
      :error -> :error
    end
  end

  defp encode_id(id) do
    id
    |> Integer.to_string()
    |> Base.encode64()
  end
end

Now you can use this custom type in your schemas:

defmodule ContentSchema do
  use Normandy.Schema

  schema do
    field :id, EncodedId
    field :content, :string
  end
end