This module contains a composable API to build schemas in a functionnal way.
Every function will return a schema and accepts an optional first argument
to merge onto, using JSV.Schema.merge/2.
See JSV.Schema.Helpers to work with a more "presets" oriented API.
Example
iex> %JSV.Schema{}
...> |> object()
...> |> properties(foo: string())
...> |> required([:foo])
%JSV.Schema{type: :object, properties: %{foo: %JSV.Schema{type: :string}}, required: [:foo]}Summary
Functions
Defines or merges onto a JSON Schema with allOf: schemas.
Defines or merges onto a JSON Schema with anyOf: schemas.
Defines or merges onto a JSON Schema with type: :array and items: item_schema.
Defines or merges onto a JSON Schema with type: :boolean.
Defines or merges onto a JSON Schema with type: :string and format: :date.
Defines or merges onto a JSON Schema with type: :string and format: :"date-time".
Defines or merges onto a JSON Schema with type: :string and format: :email.
Does not set the type: :string on the schema. Use string_of/2 for a
shortcut.
Defines or merges onto a JSON Schema with type: :integer.
Does not set the type: :array on the schema. Use array_of/2 for a
shortcut.
Defines or merges onto a JSON Schema with type: :integer and maximum: -1.
Defines or merges onto a JSON Schema with type: :string and minLength: 1.
Defines or merges onto a JSON Schema with type: :integer and minimum: 0.
Defines or merges onto a JSON Schema with type: :number.
Defines or merges onto a JSON Schema with type: :object.
Defines or merges onto a JSON Schema with oneOf: schemas.
Defines or merges onto a JSON Schema with type: :integer and minimum: 1.
Does not set the type: :object on the schema. Use props/2 for a
shortcut.
Defines or merges onto a JSON Schema with type: :object and properties: properties.
A struct-based schema module name is not a valid reference. Modules should be
passed directly where a schema (and not a $ref) is expected.
Defines a JSON Schema with required: keys or adds the given keys if the
base schema already has a :required
definition.
Defines or merges onto a JSON Schema with type: :string.
Defines or merges onto a JSON Schema with type: :string and format: format.
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_atom()].
Accepts a list of atoms and validates that a given value is a string representation of one of the given atoms.
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_boolean()].
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_existing_atom()].
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_float()].
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_integer()].
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_number()].
Defines or merges onto a JSON Schema with type: :string and format: :uri.
Defines or merges onto a JSON Schema with type: :string and format: :uuid.
Types
@type properties() :: [{property_key(), JSV.Schema.schema()}] | %{optional(property_key()) => JSV.Schema.schema()}
Functions
@spec all_of(JSV.Schema.merge_base(), [JSV.Schema.schema()]) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with allOf: schemas.
@spec any_of(JSV.Schema.merge_base(), [JSV.Schema.schema()]) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with anyOf: schemas.
@spec array_of(JSV.Schema.merge_base(), JSV.Schema.schema()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :array and items: item_schema.
@spec boolean(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :boolean.
@spec date(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :date.
@spec datetime(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :"date-time".
@spec email(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :email.
@spec format(JSV.Schema.merge_base(), atom() | binary()) :: JSV.Schema.schema()
Does not set the type: :string on the schema. Use string_of/2 for a
shortcut.
@spec integer(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer.
@spec items(JSV.Schema.merge_base(), JSV.Schema.schema()) :: JSV.Schema.schema()
Does not set the type: :array on the schema. Use array_of/2 for a
shortcut.
@spec neg_integer(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and maximum: -1.
@spec non_empty_string(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and minLength: 1.
@spec non_neg_integer(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and minimum: 0.
@spec number(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :number.
@spec object(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :object.
See props/2 to define the properties as well.
@spec one_of(JSV.Schema.merge_base(), [JSV.Schema.schema()]) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with oneOf: schemas.
@spec pos_integer(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and minimum: 1.
@spec properties(JSV.Schema.merge_base(), properties()) :: JSV.Schema.schema()
Does not set the type: :object on the schema. Use props/2 for a
shortcut.
@spec props(JSV.Schema.merge_base(), properties()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :object and properties: properties.
@spec ref(JSV.Schema.merge_base(), String.t()) :: JSV.Schema.schema()
A struct-based schema module name is not a valid reference. Modules should be
passed directly where a schema (and not a $ref) is expected.
Example
For instance to define a user property, this is valid:
props(user: UserSchema)The following is invalid:
# Do not do this
props(user: ref(UserSchema))@spec required(JSV.Schema.merge_base(), [atom() | binary()]) :: JSV.Schema.schema()
Defines a JSON Schema with required: keys or adds the given keys if the
base schema already has a :required
definition.
Existing required keys are preserved.
Examples
iex> JSV.Schema.Composer.required(%{}, [:a, :b])
%{required: [:a, :b]}
iex> JSV.Schema.Composer.required(%{required: nil}, [:a, :b])
%{required: [:a, :b]}
iex> JSV.Schema.Composer.required(%{required: [:c]}, [:a, :b])
%{required: [:a, :b, :c]}
iex> JSV.Schema.Composer.required(%{required: [:a]}, [:a])
%{required: [:a, :a]}Use JSV.Schema.merge/2 to replace existing required keys.
iex> JSV.Schema.merge(%{required: [:a, :b, :c]}, required: [:x, :y, :z])
%{required: [:x, :y, :z]}@spec string(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string.
@spec string_of(JSV.Schema.merge_base(), atom() | binary()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: format.
@spec string_to_atom(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_atom()].
@spec string_to_atom_enum(JSV.Schema.merge_base(), [atom()]) :: JSV.Schema.schema()
Accepts a list of atoms and validates that a given value is a string representation of one of the given atoms.
On validation, a cast will be made to return the original atom value.
This is useful when dealing with enums that are represented as atoms in the codebase, such as Oban job statuses or other Ecto enum types.
iex> schema = JSV.Schema.Composer.props(status: JSV.Schema.Composer.string_to_atom_enum([:executing, :pending]))
iex> root = JSV.build!(schema, atoms: true)
iex> JSV.validate(%{"status" => "pending"}, root)
{:ok, %{"status" => :pending}}Does not support nil
This function sets the string type on the schema. If nil is given in the
enum, the corresponding valid JSON value will be the "nil" string rather
than null
@spec string_to_boolean(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_boolean()].
@spec string_to_existing_atom(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_existing_atom()].
@spec string_to_float(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_float()].
@spec string_to_integer(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_integer()].
@spec string_to_number(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and x-jsv-cast: [JSV.Cast.string_to_number()].
@spec uri(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :uri.
@spec uuid(JSV.Schema.merge_base()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :uuid.