View Source Goal ⚽

Goal is a parameter validation library based on Ecto. It can be used with JSON APIs, HTML controllers and LiveViews.

Goal builds a changeset from a validation schema and controller or LiveView parameters, and returns the validated parameters or Ecto.Changeset, depending on the function you use.

If your frontend and backend use different parameter cases, you can recase parameter keys with the :recase_keys option. PascalCase, camelCase, kebab-case and snake_case are supported.

You can configure your own regexes for password, email, and URL format validations. This is helpful in case of backward compatibility, where Goal's defaults might not match your production system's behavior.

installation

Installation

Add goal to the list of dependencies in mix.exs:

def deps do
  [
    {:goal, "~> 0.2"}
  ]
end

examples

Examples

Goal can be used with LiveViews and JSON and HTML controllers.

example-with-controllers

Example with controllers

With JSON and HTML-based APIs, Goal takes the params from a controller action, validates those against a validation schema using validate/3, and returns an atom-based map or an error changeset.

defmodule MyApp.SomeController do
  use MyApp, :controller
  use Goal

  def create(conn, params) do
    with {:ok, attrs} <- validate(:create, params)) do
      ...
    else
      {:error, changeset} -> {:error, changeset}
    end
  end

  defparams :create do
    required :uuid, :string, format: :uuid
    required :name, :string, min: 3, max: 3
    optional :age, :integer, min: 0, max: 120
    optional :gender, :enum, values: ["female", "male", "non-binary"]

    optional :data, :map do
      required :color, :string
      optional :money, :decimal
      optional :height, :float
    end
  end
end

example-with-liveviews

Example with LiveViews

With LiveViews, Goal builds a changeset in mount/3 that is assigned in the socket, and then it takes the params from handle_event/3, validates those against a validation schema, and returns an atom-based map or an error changeset.

defmodule MyApp.SomeLiveView do
  use MyApp, :live_view
  use Goal

  def mount(params, _session, socket) do
    changeset = changeset(:new, %{})
    socket = assign(socket, :changeset, changeset)

    {:ok, socket}
  end

  def handle_event("validate", %{"some" => params}, socket) do
    changeset = changeset(:new, params)
    socket = assign(socket, :changeset, changeset)

    {:noreply, socket}
  end

  def handle_event("save", %{"some" => params}, socket) do
    with {:ok, attrs} <- validate(:new, params)) do
      ...
    else
      {:error, changeset} -> {:noreply, assign(socket, :changeset, changeset)}
    end
  end

  defparams :new do
    required :uuid, :string, format: :uuid
    required :name, :string, min: 3, max: 3
    optional :age, :integer, min: 0, max: 120
    optional :gender, :enum, values: ["female", "male", "non-binary"]

    optional :data, :map do
      required :color, :string
      optional :money, :decimal
      optional :height, :float
    end
  end
end

example-with-isolated-schemas

Example with isolated schemas

Validation schemas can be defined in a separate namespace, for example MyAppWeb.MySchema:

defmodule MyAppWeb.MySchema do
  use Goal

  defparams :show do
    required :id, :string, format: :uuid
    optional :query, :string
  end
end

defmodule MyApp.SomeController do
  use MyApp, :controller

  alias MyAppWeb.MySchema

  def show(conn, params) do
    with {:ok, attrs} <- MySchema.validate(:show, params) do
      ...
    else
      {:error, changeset} -> {:error, changeset}
    end
  end
end

features

Features

deeply-nested-maps

Deeply nested maps

Goal efficiently builds error changesets for nested maps, and has support for lists of nested maps. There is no limitation on depth.

use Goal

defparams do
  optional :nested_map, :map do
    required :id, :integer
    optional :inner_map, :map do
      required :id, :integer
      optional :map, :map do
        required :id, :integer
        optional :list, {:array, :integer}
      end
    end
  end
end

iex(1)> Goal.validate_params(schema(), params)
{:ok, %{nested_map: %{inner_map: %{map: %{id: 123, list: [1, 2, 3]}}}}}

readable-error-messages

Readable error messages

Use Goal.traverse_errors/2 to build readable errors. Phoenix by default uses Ecto.Changeset.traverse_errors/2, which works for embedded Ecto schemas but not for the plain nested maps used by Goal. Goal's traverse_errors/2 is compatible with (embedded) Ecto.Schema, so you don't have to make any changes to your existing logic.

def translate_errors(changeset) do
  Goal.traverse_errors(changeset, &translate_error/1)
end

recasing-inbound-keys

Recasing inbound keys

By default, Goal will look for the keys defined in defparams. But sometimes frontend applications send parameters in a different format. For example, in camelCase but your backend uses snake_case. For this scenario, Goal has the :recase_keys option:

config :goal,
  recase_keys: [from: :camel_case]

iex(1)> MySchema.validate(:show, %{"firstName" => "Jane"})
{:ok, %{first_name: "Jane"}}

recasing-outbound-keys

Recasing outbound keys

Use recase_keys/2 to recase outbound keys. For example, in your views:

config :goal,
  recase_keys: [to: :camel_case]

defmodule MyAppWeb.UserJSON do
  import Goal

  def show(%{user: user}) do
    recase_keys(%{data: %{first_name: user.first_name}})
  end

  def error(%{changeset: changeset}) do
    recase_keys(%{errors: Goal.Changeset.traverse_errors(changeset, &translate_error/1)})
  end
end

iex(1)> UserJSON.show(%{user: %{first_name: "Jane"}})
%{data: %{firstName: "Jane"}}
iex(2)> UserJSON.error(%Ecto.Changeset{errors: [first_name: {"can't be blank", [validation: :required]}]})
%{errors: %{firstName: ["can't be blank"]}}

bring-your-own-regex

Bring your own regex

Goal has sensible defaults for string format validation. If you'd like to use your own regex, e.g. for validating email addresses or passwords, then you can add your own regex in the configuration:

config :goal,
  uuid_regex: ~r/^[[:alpha:]]+$/,
  email_regex: ~r/^[[:alpha:]]+$/,
  password_regex: ~r/^[[:alpha:]]+$/,
  url_regex: ~r/^[[:alpha:]]+$/

available-validations

Available validations

The field types and available validations are:

Field typeValidationsDescription
:uuid:equalsstring value
:string:equalsstring value
:isstring length
:minminimum string length
:maxmaximum string length
:trimoolean to remove leading and trailing spaces
:squishboolean to trim and collapse spaces
:format:uuid, :email, :password, :url
:subsetlist of required strings
:includedlist of allowed strings
:excludedlist of disallowed strings
:integer:equalsinteger value
:isinteger value
:minminimum integer value
:maxmaximum integer value
:greater_thanminimum integer value
:less_thanmaximum integer value
:greater_than_or_equal_tominimum integer value
:less_than_or_equal_tomaximum integer value
:equal_tointeger value
:not_equal_tointeger value
:subsetlist of required integers
:includedlist of allowed integers
:excludedlist of disallowed integers
:floatall of the integer validations
:decimalall of the integer validations
:boolean:equalsboolean value
:date:equalsdate value
:time:equalstime value
:enum:valueslist of allowed values
:map:propertiesuse :properties to define the fields
{:array, :map}:propertiesuse :properties to define the fields
{:array, inner_type}inner_type can be any of the basic types
More basic typesSee Ecto.Schema for the full list

The default basic type is :string. You don't have to define this field if you are using the basic syntax.

All field types, excluding :map and {:array, :map}, can use :equals, :subset, :included, :excluded validations.

credits

Credits

This library is based on Ecto and I had to copy and adapt Ecto.Changeset.traverse_errors/2. Thanks for making such an awesome library! 🙇