JSV.Schema.Composer (jsv v0.9.0)
View SourceThis 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.
Defines or merges onto a JSON Schema with format: format.
Defines or merges onto a JSON Schema with type: :integer.
Defines or merges onto a JSON Schema with items: item_schema.
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.
Defines or merges onto a JSON Schema with properties: properties.
Defines or merges onto a JSON Schema with type: :object and properties: properties.
Defines or merges onto a JSON Schema with $ref: ref.
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 jsv-cast: JSV.Cast.string_to_atom().
Defines or merges onto a JSON Schema with type: :string, enum: enum and jsv-cast: JSV.Cast.string_to_atom().
Defines or merges onto a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_boolean().
Defines or merges onto a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_existing_atom().
Defines or merges onto a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_float().
Defines or merges onto a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_integer().
Defines or merges onto a JSON Schema with type: :string and 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(), term()) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with format: format.
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()
Defines or merges onto a JSON Schema with items: item_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()
Defines or merges onto a JSON Schema with properties: properties.
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()
Defines or merges onto a JSON Schema with $ref: ref.
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.required(%{}, [:a, :b])
%{required: [:a, :b]}
iex> JSV.Schema.required(%{required: nil}, [:a, :b])
%{required: [:a, :b]}
iex> JSV.Schema.required(%{required: [:c]}, [:a, :b])
%{required: [:a, :b, :c]}
iex> JSV.Schema.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(), term()) :: 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 jsv-cast: JSV.Cast.string_to_atom().
@spec string_to_atom_enum(JSV.Schema.merge_base(), [atom()]) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string, enum: enum and 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.
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.props(status: JSV.Schema.Composer.string_to_atom_enum([:executing, :pending]))
iex> root = JSV.build!(schema)
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 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 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 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 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 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.