JSV.Validator (jsv v0.21.2)

This is the home of the recursive validation logic.

The validator is called on the root schema, and may be called by vocabulary implementations to validate sub parts of the data built withing each vocabulary module.

Summary

Types

context()

eval_sub_path()

result()

validator()

validators()

Functions

context(validators, entrypoint, opts, feature_cast, feature_unevaluated)

Returns a new validation context targeting the given entrypoint key in the validators map, with the given validation options.

error?(vctx)

Returns whether the given context contains errors.

flat_errors(vctx)

Returns all errors collected in the context as a flat list.

list_evaluaded(vctx)

Lists the object keys and array indices of the data that were evaluated in the current evaluation frame. Used by vocabulary implementations to support the unevaluatedProperties and unevaluatedItems keywords.

merge_tracked(vctx, sub)

Merges tracking data from the sub context into the main context. This is useful to keep information defined by subschemas for the same data level as the parent schema. Such sub schemas are defined with oneOf/allOf/... or $ref.

reduce(enum, datain, vctx, fun)

Reduce over an enum with two accumulators, a user one, and the context.

return(data, vctx)

Returns the validation result for the given data, as {:ok, data, vctx} when the context holds no errors, {:error, vctx} otherwise.

to_error(vctx)

Builds a JSV.ValidationError exception from the errors collected in the context.

validate(data, subschema, vctx)

Validate the given data with the given validator. The validator is typically a sub-part of a JSV.Root struct built with JSV.build/2 such as a JSV.Subschema struct.

validate_as(data, add_eval_path, subvalidators, vctx)

Validates data with a sub part of the schema, for instance if, then or else. Data path will not change in the context.

validate_detach(data, add_eval_path, subschema, vctx)

Validate the data with the given validators but separate the current evaluation context during the validation.

validate_in(data, key, add_eval_path, subvalidators, vctx)

Validates a sub term of the data, identified by key, which can be a property name (a string), or an array index (an integer).

validate_ref(data, ref, eval_path, vctx)

Validates the data against the subschema referenced by the given key.

with_error(vctx, kind, data, args)

Adds an error of the given kind to the validation context and returns the updated context. The calling module is registered as the error formatter.

Types

context()

@type context() :: %JSV.Validator.ValidationContext{
  cast_stacks: term(),
  data_path: term(),
  errors: term(),
  eval_path: term(),
  evaluated: term(),
  feature_cast: term(),
  feature_unevaluated: term(),
  opts: term(),
  schema_path: term(),
  scope: term(),
  seen_refs: term(),
  validators: term()
}

eval_sub_path()

@type eval_sub_path() :: JSV.Builder.path_segment() | [JSV.Builder.path_segment()]

result()

@type result() :: {:ok, term(), context()} | {:error, context()}

validator()

@type validator() :: JSV.Subschema.t() | JSV.BooleanSchema.t() | {:alias_of, binary()}

validators()

@type validators() :: %{required(JSV.Key.t()) => validator()}

Functions

context(validators, entrypoint, opts, feature_cast, feature_unevaluated)

@spec context(
  %{required(JSV.Key.t()) => validator()},
  JSV.Key.t(),
  map(),
  boolean(),
  boolean()
) ::
  context()

Returns a new validation context targeting the given entrypoint key in the validators map, with the given validation options.

The two flags enable the tracking machinery for casts and for evaluated properties and items. They are computed at build time so schemas that use neither feature validate without the tracking overhead.

error?(vctx)

@spec error?(context()) :: boolean()

Returns whether the given context contains errors.

flat_errors(vctx)

@spec flat_errors(context()) :: [JSV.Validator.Error.t()]

Returns all errors collected in the context as a flat list.

list_evaluaded(vctx)

@spec list_evaluaded(context()) :: [String.t() | integer()]

merge_tracked(vctx, sub)

@spec merge_tracked(context(), context()) :: context()

Tracking data:

Evaluated paths, to work with unevaluated properties/items
Cast functions (defschema,defcast)

reduce(enum, datain, vctx, fun)

@spec reduce(Enumerable.t(), term(), context(), function()) :: result()

Reduce over an enum with two accumulators, a user one, and the context.

The callback is called with item, acc, vctx for all items in the enum, regardless of previously returned values. Returning and error tuple does not stop the iteration.
When returning {:ok, value, vctx}, value will be the new user accumulator, and the new context is carried on.
When returning {:error, vctx}, the current accumulator is not changed, but the new returned context with errors is still carried on.
Returning an ok tuple after an error tuple on a previous item does not remove the errors from the context struct.

The final return value is {:ok, acc, vctx} if all calls of the callback returned an OK tuple, {:error, vctx} otherwise.

This is useful to call all possible validators for a given piece of data, collecting all possible errors without stopping, but still returning an error in the end if some error arose.

return(data, vctx)

@spec return(term(), context()) :: result()

Returns the validation result for the given data, as {:ok, data, vctx} when the context holds no errors, {:error, vctx} otherwise.

to_error(vctx)

@spec to_error(context()) :: JSV.ValidationError.t()

Builds a JSV.ValidationError exception from the errors collected in the context.

validate(data, subschema, vctx)

@spec validate(term(), validator(), context()) :: result()

Validate the given data with the given validator. The validator is typically a sub-part of a JSV.Root struct built with JSV.build/2 such as a JSV.Subschema struct.

validate_as(data, add_eval_path, subvalidators, vctx)

@spec validate_as(term(), eval_sub_path(), validator(), context()) :: result()

Validates data with a sub part of the schema, for instance if, then or else. Data path will not change in the context.

See validate_in/5 to validate sub terms of the data.

validate_detach(data, add_eval_path, subschema, vctx)

@spec validate_detach(term(), eval_sub_path(), validator(), context()) :: result()

Validate the data with the given validators but separate the current evaluation context during the validation.

Currently evaluated properties or items will not be seen as evaluated during the validation by the given subschema.

validate_in(data, key, add_eval_path, subvalidators, vctx)

@spec validate_in(
  term(),
  JSV.Builder.path_segment(),
  eval_sub_path(),
  validator(),
  context()
) ::
  result()

Validates a sub term of the data, identified by key, which can be a property name (a string), or an array index (an integer).

See validate_as/4 to validate the same data point with a nested keyword. For instance if, then or else.

validate_ref(data, ref, eval_path, vctx)

@spec validate_ref(term(), JSV.Key.t(), eval_sub_path(), context()) :: result()

Validates the data against the subschema referenced by the given key.

A reference that is already being evaluated with the same data is an infinite recursion, in that case the data is considered valid, as per JSON Schema core 9.4.1.

with_error(vctx, kind, data, args)

(macro)

Adds an error of the given kind to the validation context and returns the updated context. The calling module is registered as the error formatter.

The args are a keyword list or map of values used when formatting the error message, generally the values extracted from the schema keyword and the reason of the failure.