Exonerate (exonerate v0.1.0) View Source

An opinionated JSONSchema compiler for elixir.

Currently supports JSONSchema draft 0.7. except:

  • integer filters do not match exact integer floating point values.
  • multipleOf is not supported for the number type (don't worry, it IS supported for integers). This is because Elixir does not support a floating point remainder guard, and also because it is impossible for a floating point to guarantee sane results (e.g. for IEEE Float64, 1.2 / 0.1 != 12)
  • currently remoteref is not supported.

For details, see: http://json-schema.org

Exonerate is automatically tested against the JSONSchema test suite.

Usage

Exonerate is 100% compile-time generated. You should include Exonerate with the runtime: false option in mix.exs.

In your module:

defmodule MyModule do
  require Exonerate

  Exonerate.function_from_string(:def, :function_name, """
  {
    "type": "string"
  }
  """)
end

The above module generates a function MyModule.function_name/1 that takes an erlang JSON term (string | number | array | map | bool | nil) and validates it based on the the JSONschema. If the term validates, it produces :ok. If the term fails to validate, it produces {:error, keyword}, where the key :json_pointer and points to the error location in the passed parameter, the :schema_pointers points to the validation that failed, and error_value is the failing inner term.

Metadata

The following metadata are accessible for the entrypoint in the jsonschema, by passing the corresponding atom.

JSONschema tagatom parameter
$id:id
$schema:schema
default:default
examples:examples
description:description
title:title

Options

The following options are available:

  • :format_options: a map of JSONpointers to tags with corresponding {"format" => "..."} filters. Exonerate ships with filters for the following default content:

    • date-time
    • date
    • time
    • ipv4
    • ipv6

    To disable these filters, pass false to the path, e.g. %{"/" => false} or %{"/foo/bar/" => false}. To specify a custom format filter, pass either function/args or mfa to the path, e.g. %{"/path/to/fun" => {Module, :fun, [123]}} The corresponding function will be called with the string as the first argument and the supplied arguments after. If you use the function/args (e.g. {:private_function, [123]}) it may be a private function in the same module. The custom function should return true on successful validation and false on failure. date-time ships with the parameter :utc which you may pass as %{"/path/to/date-time/" => [:utc]} that forces the date-time to be an ISO-8601 datetime string.

  • :entrypoint: a JSONpointer to the internal location inside of a json document where you would like to start the JSONschema. A json document might contain multiple schemasFor example:

      multischema = """
      {
        "schema1": {"type": "string"},
        "schema2": {"type": "number"}
      }
      """
      Exonerate.function_from_string(:def, :schema1, multischema, entrypoint: "/schema1")
      Exonerate.function_from_string(:def, :schema2, multischema, entrypoint: "/schema2")

    In more practical terms, this enables you to store single documents and reuse components, especially when combined with $ref tags. Exonerate will be parsimonious and minimize producing multiple functions for validation trees so long as the instantiated functions are within the same module.

Link to this section Summary

Link to this section Functions

Link to this macro

function_from_string(type, name, schema, opts \\ [])

View Source (macro)