Formata.Schema (formata v0.1.0)

Copy Markdown View Source

Schema creation, checking, and compiled-schema metadata.

Formata keeps two independent schema systems:

A JSON Schema document is never converted into a native schema, and native schemas are never exported to JSON Schema to validate data.

Compiling

iex> {:ok, schema} = Formata.Schema.compile(:native, %{name: {:required, :string}})
iex> schema.kind
:native

iex> {:ok, schema} = Formata.Schema.compile(:json_schema, %{"type" => "integer"})
iex> {schema.kind, schema.dialect}
{:json_schema, :draft2020_12}

A compiled %Formata.Schema{} is an immutable value: compile once, then pass it to Formata.validate/3 and Formata.cast/3 as often as needed.

Fields

  • :kind - :native or :json_schema
  • :dialect - :draft7 or :draft2020_12 for JSON Schema, nil for native
  • :backend - Formata.Backplane.Schema or Formata.Backplane.JsonSchema
  • :compiled - the backend representation (the checked native definition or a Formata.Backplane.JsonSchema.Types.Schema)
  • :source - the definition/document as given
  • :options - the compile options
  • :plans - precomputed native execution plans (internal)

Summary

Types

dialect()
kind()
t()

Functions

check(kind, definition, opts \\ [])

Checks a schema definition without keeping the compiled result.

compile(kind, definition, opts \\ [])

Compiles a schema of the given kind.

json_schema(document, opts \\ [])

Shortcut for compile(:json_schema, document, opts).

native(definition, opts \\ [])

Shortcut for compile(:native, definition, opts).

Types

dialect()

@type dialect() :: :draft7 | :draft2020_12

kind()

@type kind() :: :native | :json_schema

t()

@type t() :: %Formata.Schema{
  backend: module(),
  compiled: term(),
  dialect: dialect() | nil,
  kind: kind(),
  options: keyword(),
  plans: map() | nil,
  source: term()
}

Functions

check(kind, definition, opts \\ [])

@spec check(kind(), term(), keyword()) :: :ok | {:error, [Formata.Error.t(), ...]}

Checks a schema definition without keeping the compiled result.

Returns :ok or {:error, errors} with :schema errors. Checking the definition is separate from validating data.

iex> Formata.Schema.check(:native, %{age: :integer})
:ok

iex> {:error, [%Formata.Error{kind: :schema}]} = Formata.Schema.check(:native, %{age: :intger})

compile(kind, definition, opts \\ [])

@spec compile(kind(), term(), keyword()) ::
  {:ok, t()} | {:error, [Formata.Error.t(), ...]}

Compiles a schema of the given kind.

See Formata.Schema.Native.compile/2 and Formata.Schema.JSONSchema.compile/2 for the options of each kind.

json_schema(document, opts \\ [])

@spec json_schema(map() | boolean(), keyword()) ::
  {:ok, t()} | {:error, [Formata.Error.t(), ...]}

Shortcut for compile(:json_schema, document, opts).

native(definition, opts \\ [])

@spec native(term(), keyword()) :: {:ok, t()} | {:error, [Formata.Error.t(), ...]}

Shortcut for compile(:native, definition, opts).