The Ash.Type behaviour is used to define a value type in Ash.

Built in types

• :map - Ash.Type.Map
• :keyword - Ash.Type.Keyword
• :term - Ash.Type.Term
• :atom - Ash.Type.Atom
• :string - Ash.Type.String
• :integer - Ash.Type.Integer
• :file - Ash.Type.File
• :float - Ash.Type.Float
• :duration_name - Ash.Type.DurationName
• :function - Ash.Type.Function
• :boolean - Ash.Type.Boolean
• :struct - Ash.Type.Struct
• :uuid - Ash.Type.UUID
• :uuid_v7 - Ash.Type.UUIDv7
• :binary - Ash.Type.Binary
• :date - Ash.Type.Date
• :time - Ash.Type.Time
• :decimal - Ash.Type.Decimal
• :ci_string - Ash.Type.CiString
• :naive_datetime - Ash.Type.NaiveDatetime
• :utc_datetime - Ash.Type.UtcDatetime
• :utc_datetime_usec - Ash.Type.UtcDatetimeUsec
• :datetime - Ash.Type.DateTime
• :url_encoded_binary - Ash.Type.UrlEncodedBinary
• :union - Ash.Type.Union
• :module - Ash.Type.Module
• :vector - Ash.Type.Vector

Lists/Arrays

To specify a list of values, use {:array, Type}. Arrays are special, and have special constraints:

• :items (term/0) - Constraints for the elements of the list. See the contained type's docs for more.

• :min_length (non_neg_integer/0) - A minimum length for the items.

• :max_length (non_neg_integer/0) - A maximum length for the items.

• :nil_items? (boolean/0) - Whether or not the list can contain nil items. The default value is false.

• :remove_nil_items? (boolean/0) - Whether or not to remove the nil items from the list instead of adding errors. The default value is false.

• :empty_values (list of term/0) - A set of values that, if encountered, will be considered an empty list. The default value is [""].

Defining Custom Types

Generally you add use Ash.Type to your module (it is possible to add @behaviour Ash.Type and define everything yourself, but this is more work and error-prone).

Overriding the {:array, type} behaviour. By defining the *_array versions of cast_input, cast_stored, dump_to_native and apply_constraints, you can override how your type behaves as a collection. This is how the features of embedded resources are implemented. No need to implement them unless you wish to override the default behaviour. Your type is responsible for handling nil values in each callback as well.

Simple example of a float custom type

defmodule GenTracker.AshFloat do
  use Ash.Type

  @impl Ash.Type
  def storage_type(_), do: :float

  @impl Ash.Type
  def cast_input(nil, _), do: {:ok, nil}
  def cast_input(value, _) do
    Ecto.Type.cast(:float, value)
  end

  @impl Ash.Type
  def cast_stored(nil, _), do: {:ok, nil}
  def cast_stored(value, _) do
    Ecto.Type.load(:float, value)
  end

  @impl Ash.Type
  def dump_to_native(nil, _), do: {:ok, nil}
  def dump_to_native(value, _) do
    Ecto.Type.dump(:float, value)
  end
end

All the Ash built-in types are implemented with use Ash.Type so they are good examples to look at to create your own Ash.Type.

Short names

You can define short :atom_names for your custom types by adding them to your Ash configuration:

config :ash, :custom_types, [ash_float: GenTracker.AshFloat]

Doing this will require a recompilation of the :ash dependency which can be triggered by calling:

$ mix deps.compile ash --force

Composite Types

Composite types are composite in the data layer. Many data layers do not support this, but some (like AshPostgres), do. To define a composite type, the following things should be true:

1. A casted value should be a map or struct, for example for a point: %{x: 1, y: 2}
2. The data layer must support composite types, and the data layer representation will be a tuple, i.e {1, 2}
3. Define def composite?(_), do: true in your composite type
4. Define the type & constraints of each item in the tuple, and its name in the map representation: def composite_types(_), do: [{:x, :integer, []}, {:y, :integer, []}]. You can also define a storage key for each item in the tuple, if the underlying type implementation has a different reference for an item, i.e def composite_types(_), do: [{:x, :x_coord, :integer, []}, {:y, :y_coord, :integer, []}]

With the above implemented, your composite type can be used in expressions, for example:

Ash.Query.filter(expr(coordinates[:x] == 1))k

And you can also construct composite types in expressions, for example:

calculate :coordinates, :composite_point, expr(composite_type(%{x: some_value, y: some_other_value}, Point))

Constraints

Constraints are a way of validating an input type. This validation can be used in both attributes and arguments. The kinds of constraints you can apply depends on the type of data. You can find all types in Ash.Type . Each type has its own page on which the available constraints are listed. For example in Ash.Type.String you can find 5 constraints:

• :max_length
• :min_length
• :match
• :trim?
• :allow_empty?

You can also discover these constraints from iex:

$ iex -S mix
iex(1)> Ash.Type.String.constraints
[
  max_length: [
    type: :non_neg_integer,
    doc: "Enforces a maximum length on the value"
  ],
  min_length: [
    type: :non_neg_integer,
    doc: "Enforces a minimum length on the value"
  ],
  match: [
    type: {:custom, Ash.Type.String, :match, []},
    doc: "Enforces that the string matches a passed in regex"
  ],
  trim?: [type: :boolean, doc: "Trims the value.", default: true],
  allow_empty?: [
    type: :boolean,
    doc: "If false, the value is set to `nil` if it's empty.",
    default: false
  ]
]

Attribute example

To show how constraints can be used in a attribute, here is an example attribute describing a username:

defmodule MyProject.MyDomain.Account do
  # ...

  code_interface do
    define :create, action: :create
  end

  actions do
    default [:create, :read, :update, :destroy]
  end

  attributes do
    uuid_primary_key :id

    attribute :username, :string do
      constraints [
        max_length: 20,
        min_length: 3,
        match: ~r/^[a-z_-]*$/,
        trim?: true,
        allow_empty?: false
      ]
    end
  end

  # ...
end

If, when creating or updating this attribute, one of the constraints are not met, an error will be given telling you which constraint was broken. See below:

iex(1)> MyProject.MyDomain.Account.create!(%{username: "hi"})

** (Ash.Error.Invalid) Invalid Error

* Invalid value provided for username: length must be greater than or equal to 3.

"hi"

iex(2)> MyProject.MyDomain.Account.create!(%{username: "Hello there this is a long string"})

** (Ash.Error.Invalid) Invalid Error

* Invalid value provided for username: length must be less than or equal to 20.

"Hello there this is a long string"

iex(3)> MyProject.MyDomain.Account.create!(%{username: "hello there"})
** (Ash.Error.Invalid) Invalid Error

* Invalid value provided for username: must match the pattern ~r/^[a-z_-]*$/.

"hello there"

iex(4)> MyProject.MyDomain.Account.create!(%{username: ""})
** (Ash.Error.Invalid) Invalid Error

* attribute title is required

It will give you the resource as usual on successful requests:

iex(5)> MyProject.MyDomain.Account.create!(%{username: "hello"})
#MyProject.MyDomain.Account<
  __meta__: #Ecto.Schema.Metadata<:loaded, "account">,
  id: "7ba467dd-277c-4916-88ae-f62c93fee7a3",
  username: "hello",
  ...
>