A macro that creates a data schema. By default all struct fields are required but you can specify that a field be optional by passing the correct option in. See the Options section below for more.

Field Types

There are 5 kinds of struct fields we can have:

1. field - The value will be a casted value from the source data.
2. list_of - The value will be a list of casted values created from the source data.
3. has_one - The value will be created from a nested data schema (so will be a struct)
4. has_many - The value will be created by casting a list of values into a data schema. (You end up with a list of structs defined by the provided schema). Similar to has_many in ecto
5. aggregate - The value will a casted value formed from multiple bits of data in the source.

Options

Available options are:

• :optional? - specifies whether or not the field in the struct should be included in the @enforce_keys for the struct. By default all fields are required but you can mark them as optional by setting this to true. This will also be checked when creating a struct with DataSchema.to_struct/2 returning an error if the required field is null.

For example:

defmodule Sandwich do
  require DataSchema

  DataSchema.data_schema([
    field: {:type, "the_type", &{:ok, String.upcase(&1)}, optional?: true},
  ])
end

Examples

See the guides for more in depth examples but below you can see how we create a schema that will take a map of data and create a struct out of it. Given the following schema:

defmodule Sandwich do
  require DataSchema

  DataSchema.data_schema([
    field: {:type, "the_type", &{:ok, String.upcase.(&1)}},
    list_of: {:fillings, "the_fillings", &({:ok, String.downcase(&1["name"])})}
  ])
end

input_data = %{
  "the_type" => "fake steak",
  "the_fillings" => [
    %{"name" => "fake stake", "good?" => true},
    %{"name" => "SAUCE"},
    %{"name" => "sweetcorn"},
  ]
}

DataSchema.to_struct(input_data, Sandwich)
# outputs the following:
%Sandwich{
  type: "FAKE STEAK",
  fillings: ["fake stake", "sauce", "sweetcorn"],
}

Accepts an data schema module and some source data and attempts to create the struct defined in the schema from the source data recursively.

We essentially visit each field in the schema and extract the data the field points to from the sauce data, passing it to the field's casting function before setting the result of that as the value on the struct.

This function takes a simple approach to creating the struct - whatever you return from a casting function will be set as the value of the struct field. You should raise if you want casting to fail.

Examples

data = %{ "spice" => "enables space travel" }

defmodule Foo do
  require DataSchema

  DataSchema.data_schema(
    field: {:a_rocket, "spice", &({:ok, &1})}
  )
end

DataSchema.to_struct(data, Foo)
# => Outputs the following:
%Foo{a_rocket: "enables space travel"}

Creates a struct or map from the provided arguments. This function can be used to define runtime schemas for the most dynamic of cases. This means you don't have to define a schema at compile time using the DataShema.data_schema/1 macro.

Examples

Creating a struct:

defmodule Run do
  defstruct [:time]
end

input = %{"time" => "10:00"}
fields = [
  field: {:time, "time", &{:ok, to_string(&1)}}
]
DataSchema.to_struct(input, Run, fields, DataSchema.MapAccessor)
{:ok, %Run{time: "10:00"}}

Creating a map:

input = %{"time" => "10:00"}
fields = [
  field: {:time, "time", &{:ok, to_string(&1)}}
]
DataSchema.to_struct(input, %{}, fields, DataSchema.MapAccessor)
{:ok, %{time: "10:00"}}