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 tag | atom 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 returntrue
on successful validation andfalse
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.