JSONSchex.Schema (jsonschex v0.11.2)

Copy Markdown View Source

Compile-time helpers for embedding compiled JSON Schemas directly into modules.

Use compile!/2 when the schema is fully known at compile time, such as in generated modules, router metadata, module attributes, Plug/Phoenix code, and test fixtures.

Examples

iex> require JSONSchex.Schema
iex> schema = JSONSchex.Schema.compile!(%{"type" => "integer", "minimum" => 10})
iex> JSONSchex.validate(schema, 10)
:ok

iex> defmodule JSONSchexSchemaMacroExample do
...>   require JSONSchex.Schema
...>   @schema JSONSchex.Schema.compile!(%{"type" => "string", "format" => "email"}, format_assertion: true)
...>   def schema, do: @schema
...> end
iex> {:error, [_]} = JSONSchex.validate(JSONSchexSchemaMacroExample.schema(), "not-an-email")

Summary

Functions

compile!(schema_ast, opts_ast \\ [])

Compiles a static schema literal at compile time and embeds the compiled JSONSchex.Types.Schema directly into the caller module.

compile_fragment!(document_ast, opts_ast)

Compiles a static JSON Schema fragment at compile time and embeds the compiled JSONSchex.Types.Schema directly into the caller module.

Functions

compile!(schema_ast, opts_ast \\ [])

(macro)

Compiles a static schema literal at compile time and embeds the compiled JSONSchex.Types.Schema directly into the caller module.

The schema argument must be a compile-time literal map or boolean. Options must also be compile-time literals. If you pass :loader, prefer a remote capture such as &MyLoader.fetch/1 so the compiled schema remains embeddable.

Options

The available options are the same as JSONSchex.compile/2:

  • :loader — (uri -> {:ok, map()} | {:error, term()}) for remote $ref schemas

  • :base_uri — Starting base URI for resolving relative references
  • :format_assertion — Explicitly enable format validation (default: false); an active Draft 2020-12 format-assertion vocabulary also enables it.
  • :content_assertion — Enable strict content vocabulary validation (default: false)
  • :draft — Use "draft7" or "draft2020_12" (strings, not atoms). A recognized root $schema selects the draft when this option is omitted; a conflicting option raises a compile error. Without either, Draft 2020-12 is the default.

Examples

iex> require JSONSchex.Schema
iex> schema = JSONSchex.Schema.compile!(%{"type" => "string", "format" => "email"}, format_assertion: true)
iex> {:error, [_]} = JSONSchex.validate(schema, "not-an-email")

iex> draft7 = JSONSchex.Schema.compile!(%{"$schema" => "http://json-schema.org/draft-07/schema#", "items" => [%{"type" => "integer"}], "additionalItems" => false})
iex> JSONSchex.validate(draft7, [1])
:ok
iex> match?({:error, [_ | _]}, JSONSchex.validate(draft7, [1, 2]))
true

compile_fragment!(document_ast, opts_ast)

(macro)

Compiles a static JSON Schema fragment at compile time and embeds the compiled JSONSchex.Types.Schema directly into the caller module.

Accepts a containing document plus options. Local references inside the fragment resolve against the containing document, which is useful for OpenAPI 3.1 request/response schemas.

Examples

iex> require JSONSchex.Schema
iex> schema = JSONSchex.Schema.compile_fragment!(
...>   %{"components" => %{"schemas" => %{"Name" => %{"type" => "string"}}}, "schema" => %{"$ref" => "#/components/schemas/Name"}},
...>   entry: "#/schema"
...> )
iex> JSONSchex.validate(schema, "Alice")
:ok