JSON Schema documents compiled and validated by Formata.JSONSchema.
Documents are JSON-compatible maps (string keys) or the boolean schemas
true/false. They are handed to Formata.JSONSchema as they are; Formata
never converts them to native schemas.
Dialects
Draft 2020-12 and Draft 7 are supported.
- A recognized root
$schemaselects the dialect:https://json-schema.org/draft/2020-12/schemaorhttp://json-schema.org/draft-07/schema#. dialect: :draft7 | :draft2020_12selects it explicitly. Conflicting with the document's$schemais a:schema/:dialect_conflicterror.- Without either, Draft 2020-12 is used.
- A
$schemathat is not one of the recognized meta-schemas is rejected (:schema/:unknown_dialect) unlessdialect:is given or a:loaderis provided to resolve the custom meta-schema and its vocabularies.
Unknown keywords and extension keywords (for example x-*) are accepted as
annotations, as the dialects permit.
Format assertion
format is an annotation by default and does not reject data.
Pass format_assertion: true to assert the formats implemented by
Formata.JSONSchema (email, date-time, date, time, uri, ipv4,
ipv6, hostname, regex, uuid, ...). Unknown format names are always
accepted. In Draft 2020-12, a custom meta-schema that enables the
format-assertion vocabulary also enables assertion; a document without
$schema uses the standard vocabularies, in which format is an annotation.
Internationalized names cannot be checked without the IDNA2008 Unicode
tables, which Formata does not include. When hostname, email,
idn-hostname, or idn-email is asserted and the value contains an A-label
(xn--...) or a non-ASCII label, validation stops with a single
:unsupported / :unsupported_format error at the value's path: the value
is neither accepted nor rejected as if it had been checked, and the result
cannot be inverted by not, anyOf, oneOf, or if. A value that is
invalid for another reason (for example an ASCII label with _) is still a
:validation / :format error. Plain ASCII host names are fully checked.
References
Local references (#/$defs/..., #anchor, embedded $id resources) are
resolved without any I/O. Remote references are only loaded through an
explicit :loader function (uri -> {:ok, map | boolean} | {:error, term});
Formata performs no network access. A reference that cannot be resolved fails
validation with a :schema / :unresolved_ref error, never a silent pass.
Defaults and other annotations
default, examples, title, and other annotations never modify data.
Formata.cast/3 is not available for JSON Schemas because they define no
transformations.
Data model
Data must be in the JSON data model: nil, booleans, numbers, strings,
lists, and maps with string keys. Other terms (atom keys, Date, tuples,
special-float atoms, ...) are reported as :unsupported / :non_json_value;
convert them explicitly first (see Formata.Transform).
Additional properties are governed only by the document
(additionalProperties, unevaluatedProperties); there is no facade option
that overrides them.
Summary
Functions
Checks a schema document against its built-in Draft 7 or 2020-12 meta-schema
without validating an instance. Returns :ok or structured schema errors.
Accepts the compile options and the registration limits listed in preflight/2.
Only depth, node and byte limits apply to this document-only check.
References in the schema document are not required to resolve by this operation.
Compiles a JSON Schema document.
Compiles a schema for registration after offline meta-schema validation and an eager reference audit, including unused branches and definitions.
Functions
Checks a schema document against its built-in Draft 7 or 2020-12 meta-schema
without validating an instance. Returns :ok or structured schema errors.
Accepts the compile options and the registration limits listed in preflight/2.
Only depth, node and byte limits apply to this document-only check.
References in the schema document are not required to resolve by this operation.
@spec compile(map() | boolean(), keyword()) :: {:ok, Formata.Schema.t()} | {:error, [Formata.Error.t(), ...]}
Compiles a JSON Schema document.
Options
:dialect-:draft7or:draft2020_12:format_assertion- assertformat(defaultfalse):content_assertion- assertcontentEncoding/contentMediaType/contentSchema(defaultfalse):loader-(uri -> {:ok, schema} | {:error, term})for remote references and custom meta-schemas:base_uri- base URI for resolving relative references
Compiles a schema for registration after offline meta-schema validation and an eager reference audit, including unused branches and definitions.
Returns {:ok, Formata.Schema.t()} or structured errors. Supports scoped
$id, anchors, recursive pointers and static targets of $dynamicRef.
Instance-dependent dynamic scope selection still happens during validation.
Annotation/instance values such as default, enum and const are not
interpreted as schemas unless selected by a reference.
External resources require registry: %{uri => document} or an explicit
loader:. Loaded resources are checked before compilation and captured in
the returned schema, so later validation performs no loader calls or I/O.
Loader responses may include %{document: schema, base_uri: uri}.
Limits: max_depth: 128 per document, max_nodes: 100_000 across documents,
max_bytes: 1_048_576 per document (Erlang external term size),
max_refs: 10_000, and max_resources: 1_000. Limits are nonnegative;
exhaustion returns :schema / :limit_exceeded. Invalid options return
:unsupported / :invalid_option. No network loader is supplied by Formata.