JSV.Schema.Helpers (jsv v0.15.2)

Schema presets are functions that take zero or more arguments and return predefined schemas. Those predefined schemas are not JSV.Schema structs but raw maps.

Each function has a second version with an additional extra argument that will be combined with the predefined schema using JSV.Schema.combine/2.

Note that the extra attributes cannot override what is defined in the preset.

Example

%{
  properties: %{
    foo: integer(),
    bar: integer(description: "An actual bar", minimum: 10),
    baz: any_of([MyApp.Baz,MyApp.OldBaz], description: "Baz baz baz")
  }
}

all_of(schemas, extra \\ nil)

@spec all_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns a JSON Schema with allOf: schemas.

any_of(schemas, extra \\ nil)

@spec any_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns a JSON Schema with anyOf: schemas.

array_of(item_schema, extra \\ nil)

@spec array_of(JSV.Schema.schema(), JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns a JSON Schema with type: :array and items: item_schema.

boolean(extra \\ nil)

@spec boolean(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :boolean.

const(const, extra \\ nil)

@spec const(term(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with const: const.

date(extra \\ nil)

@spec date(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: :date.

datetime(extra \\ nil)

@spec datetime(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: :"date-time".

email(extra \\ nil)

@spec email(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: :email.

enum(enum, extra \\ nil)

@spec enum(list(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns 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.

format(format, extra \\ nil)

@spec format(term(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with format: format.

Does not set the type: :string on the schema. Use string_of/2 for a shortcut.

integer(extra \\ nil)

@spec integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :integer.

neg_integer(extra \\ nil)

@spec neg_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :integer and maximum: -1.

non_empty_string(extra \\ nil)

@spec non_empty_string(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and minLength: 1.

non_neg_integer(extra \\ nil)

@spec non_neg_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :integer and minimum: 0.

number(extra \\ nil)

@spec number(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :number.

object(extra \\ nil)

@spec object(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :object.

See the props/2 function that accepts properties as a first argument.

one_of(schemas, extra \\ nil)

@spec one_of([JSV.Schema.schema()], JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns a JSON Schema with oneOf: schemas.

pos_integer(extra \\ nil)

@spec pos_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :integer and minimum: 1.

properties(properties, extra \\ nil)

@spec properties(
  properties(),
  JSV.Schema.attributes() | nil
) :: JSV.Schema.schema()

Returns a JSON Schema with properties: properties.

Does not set the type: :object on the schema. Use props/2 for a shortcut.

props(properties, extra \\ nil)

@spec props(
  properties(),
  JSV.Schema.attributes() | nil
) :: JSV.Schema.schema()

Returns a JSON Schema with type: :object and properties: properties.

ref(ref, extra \\ nil)

@spec ref(String.t(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns 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))

string(extra \\ nil)

@spec string(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string.

string_enum_to_atom(enum, extra \\ nil)

@spec string_enum_to_atom([atom()], JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns 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.

string_enum_to_atom_or_nil(enum, extra \\ nil)

@spec string_enum_to_atom_or_nil([atom()], JSV.Schema.attributes() | nil) ::
  JSV.Schema.schema()

Returns 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.

string_of(format, extra \\ nil)

@spec string_of(term(), JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: format.

string_to_atom(extra \\ nil)

@spec string_to_atom(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_atom().

string_to_boolean(extra \\ nil)

@spec string_to_boolean(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_boolean().

string_to_existing_atom(extra \\ nil)

@spec string_to_existing_atom(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_existing_atom().

string_to_float(extra \\ nil)

@spec string_to_float(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_float().

string_to_integer(extra \\ nil)

@spec string_to_integer(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_integer().

string_to_number(extra \\ nil)

@spec string_to_number(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and jsv-cast: JSV.Cast.string_to_number().

uri(extra \\ nil)

@spec uri(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: :uri.

uuid(extra \\ nil)

@spec uuid(JSV.Schema.attributes() | nil) :: JSV.Schema.schema()

Returns a JSON Schema with type: :string and format: :uuid.

Types

properties()

@type properties() ::
  [{property_key(), JSV.Schema.schema()}]
  | %{optional(property_key()) => JSV.Schema.schema()}

property_key()

@type property_key() :: atom() | binary()

Functions

nullable(schema)

@spec nullable(map() | module()) :: map()

Makes a schema nullable by adding :null to the allowed types.

Example

iex> nullable(integer())
%{type: [:integer, :null]}

iex> nullable(%{type: :integer, anyOf: [%{minimum: 1}, %{maximum: -1}]})
%{
  type: [:integer, :null],
  anyOf: [%{type: :null}, %{minimum: 1}, %{maximum: -1}]
}

iex> nullable(%{type: :integer, oneOf: [%{minimum: 1}, %{maximum: -1}]})
%{
  type: [:integer, :null],
  oneOf: [%{type: :null}, %{minimum: 1}, %{maximum: -1}]
}

When given a schema module, wraps it in an anyOf that allows either the module's schema or null:

iex> defmodule Position do
...>   use JSV.Schema
...>   defschema x: integer(), y: integer()
...> end
iex> nullable(Position)
%{anyOf: [%{type: :null}, Position]}

iex> defmodule Point do
...>   def json_schema do
...>     %{
...>       "properties" => %{
...>         "x" => %{"type" => "integer"},
...>         "y" => %{"type" => "integer"}
...>       }
...>     }
...>   end
...> end
iex> nullable(Point)
%{anyOf: [%{type: :null}, Point]}

optional(schema, opts \\ [])

@spec optional(
  term(),
  keyword()
) :: {:__optional__, term(), keyword()}

Marks a schema as optional when using the keyword list syntax with JSV.defschema/1 or JSV.defschema/3.

This is useful for recursive module references where you want to avoid infinite nesting requirements. When used in property list syntax with defschema, the property will not be marked as required.

defschema name: string(),
          parent: optional(MySelfReferencingModule)

Skipping optional keys during JSON serialization

This is only applicable to schema defined with JSV.defschema/3. The more generic macro JSV.defschema/1 let you implement a full module so you must implement the protocols yourself, or use anyOf: null/sub schema for some properties.

When encoding a struct to JSON, optional value (set as nil in the struct) are still rendered, which may be invalid if someone needs to validate the serialized value with the original schema. As the optional properties are not required, the :nskip option (for "normalization skip") with a constant value can be given. The value will not be serialized if it matches the value.

defschema name: string(),
          parent: optional(MySelfReferencingModule, nskip: nil)

sigil_SD(arg, list)

(macro)

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!"

left ~> right

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]
}

JSV.Schema.Helpers (jsv v0.15.2)

Summary

Schema Presets

Types

Functions

Schema Presets

Example

all_of(schemas, extra \\ nil)

any_of(schemas, extra \\ nil)

array_of(item_schema, extra \\ nil)

boolean(extra \\ nil)

const(const, extra \\ nil)

date(extra \\ nil)

datetime(extra \\ nil)

email(extra \\ nil)

enum(enum, extra \\ nil)

format(format, extra \\ nil)

integer(extra \\ nil)

neg_integer(extra \\ nil)

non_empty_string(extra \\ nil)

non_neg_integer(extra \\ nil)

number(extra \\ nil)

object(extra \\ nil)

one_of(schemas, extra \\ nil)

pos_integer(extra \\ nil)

properties(properties, extra \\ nil)

props(properties, extra \\ nil)

ref(ref, extra \\ nil)

Example

string(extra \\ nil)

string_enum_to_atom(enum, extra \\ nil)

Does not support nil

string_enum_to_atom_or_nil(enum, extra \\ nil)

string_of(format, extra \\ nil)

string_to_atom(extra \\ nil)

string_to_boolean(extra \\ nil)

string_to_existing_atom(extra \\ nil)

string_to_float(extra \\ nil)

string_to_integer(extra \\ nil)

string_to_number(extra \\ nil)

uri(extra \\ nil)

uuid(extra \\ nil)

Types

properties()

property_key()

Functions

nullable(schema)

Example

optional(schema, opts \\ [])

Skipping optional keys during JSON serialization

sigil_SD(arg, list)

Example

left ~> right

Example

Does not support `nil`