JSV.Schema.Helpers (jsv v0.9.0)
View SourceHelpers to define schemas in plain Elixir code.
Summary
Schema Presets
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 const: const.
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 enum: enum.
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 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 or merges onto a JSON Schema with type: :string.
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, :null], enum: enum and jsv-cast: JSV.Cast.string_to_atom_or_nil().
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 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
The Schema Description sigil.
A sigil used to embed long texts in schemas descriptions. Replaces all combinations of whitespace by a single whitespace and trims the string.
It does not support any modifier.
Note that newlines are perfectly fine in schema descriptions, as they are
simply encoded as "\n". This sigil is intended for schemas that need to be
compressed because they are sent over the wire repeatedly (like in HTTP APIs
or when working with LLMs).
Example
iex> ~SD"""
...> This schema represents an elixir.
...>
...> An elixir is a potion with positive outcomes!
...> """
"This schema represents an elixir. An elixir is a potion with positive outcomes!"An alias for JSV.Schema.combine/2.
Example
iex> object(description: "a user")
...> ~> any_of([AdminSchema, CustomerSchema])
...> ~> properties(foo: integer())
%{
type: :object,
description: "a user",
properties: %{foo: %{type: :integer}},
anyOf: [AdminSchema, CustomerSchema]
}Schema Presets
@spec all_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with allOf: schemas.
@spec any_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with anyOf: schemas.
@spec array_of(JSV.Schema.schema(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :array and items: item_schema.
@spec boolean(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :boolean.
@spec const(term(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with const: const.
@spec date(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :date.
@spec datetime(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :"date-time".
@spec email(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :email.
@spec enum(list(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with enum: enum.
Note that in the JSON Schema specification, if the enum contains 1 then
1.0 is a valid value.
@spec format(term(), JSV.Schema.attributes() | nil) :: 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.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer.
@spec neg_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and maximum: -1.
@spec non_empty_string(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and minLength: 1.
@spec non_neg_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and minimum: 0.
@spec number(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :number.
@spec object(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :object.
See the props/2 function that accepts properties as a first argument.
@spec one_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with oneOf: schemas.
@spec pos_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :integer and minimum: 1.
@spec properties( properties(), JSV.Schema.attributes() | nil ) :: 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( properties(), JSV.Schema.attributes() | nil ) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :object and properties: properties.
@spec ref(String.t(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with $ref: ref.
Returns a schema referencing the given 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 string(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string.
@spec string_enum_to_atom([atom()], JSV.Schema.attributes() | nil) :: 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 returns a schema that validates 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 = props(status: string_enum_to_atom([: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. See string_enum_to_atom_or_nil/2.
@spec string_enum_to_atom_or_nil([atom()], JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: [:string, :null], enum: enum and jsv-cast: JSV.Cast.string_to_atom_or_nil().
Like string_enum_to_atom/2 but also accepts the null JSON value as part of the
enum.
@spec string_of(term(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: format.
@spec string_to_atom(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_atom().
@spec string_to_boolean(JSV.Schema.attributes() | nil) :: 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.attributes() | nil) :: 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.attributes() | nil) :: 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.attributes() | nil) :: 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.attributes() | nil) :: 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.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :uri.
@spec uuid(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()
Defines or merges onto a JSON Schema with type: :string and format: :uuid.