jammy (3) JSON::Validator::Schema.3pm.gz
NAME
JSON::Validator::Schema - Base class for JSON::Validator schemas
SYNOPSIS
Basics
# Create a new schema from a file on disk
# It is also possible to create the object from JSON::Validator::Schema,
# but you most likely want to use one of the subclasses.
my $schema = JSON::Validator::Schema::Draft7->new('file:///cool/beans.yaml');
# Validate the schema
die $schema->errors->[0] if $schema->is_invalid;
# Validate data
my @errors = $schema->validate({some => 'data'});
die $errors[0] if @errors;
Shared store
my $store = JSON::Validator::Store->new;
my $schema = JSON::Validator::Schema::Draft7->new(store => $store);
# Will not fetch the fike from web, if the $store has already retrived
# the schema
$schema->resolve('https://api.example.com/cool/beans.json');
Make a new validation class
package JSON::Validator::Schema::SomeSchema;
use Mojo::Base 'JSON::Validator::Schema';
has specification => 'https://api.example.com/my/spec.json#';
1;
DESCRIPTION
JSON::Validator::Schema is the base class for JSON::Validator::Schema::Draft4,
JSON::Validator::Schema::Draft6, JSON::Validator::Schema::Draft7, JSON::Validator::Schema::Draft201909,
JSON::Validator::Schema::OpenAPIv2 and JSON::Validator::Schema::OpenAPIv3.
Any of the classes above can be used instead of JSON::Validator if you know which draft/version you are
working with up front.
Validation
JSON::Validator::Schema can both validate user input and the schema itself.
• A JSON::Validator::Schema represents a set of validation rules stored in "data". The rules stored in
the "data" attribute will be used when calling the "validate" method.
• The input to "validate()" could be some data from a web request or some other user input. "validate()"
returns a list of JSON::Validator::Error objects, if the user input (input to "validate()") contains
invalid data.
• The "errors" and "is_invalid" attributes has nothing to do with user input, meaning it is not relevant
for "validate". These two accessors are used to check if the rules/schema stored in "data" is correct.
The validation is performed against the "specification". This is pretty much the same as:
my $jv = JSON::Validator->new;
my $draft7 = $jv->schema('http://json-schema.org/draft-07/schema#')->schema;
my $schema = $jv->schema({name => {type => 'string'}})->schema;
my @errors = $draft7->validate($schema->data);
ATTRIBUTES
errors
$array_ref = $schema->errors;
Holds the errors after checking "data" against "specification". $array_ref containing no elements means
"data" is valid. Each element in the array-ref is a JSON::Validator::Error object.
This attribute is not changed by "validate". It only reflects if the $schema is valid.
formats
$hash_ref = $schema->formats;
$schema = $schema->formats(\%hash);
Holds a hash-ref, where the keys are supported JSON type "formats", and the values holds a code block
which can validate a given format. A code block should return "undef" on success and an error string on
error:
sub { return defined $_[0] && $_[0] eq "42" ? undef : "Not the answer." };
See JSON::Validator::Formats for a list of supported formats.
recursive_data_protection
The value of this attribute will be copied into the created "schema". See "recursive_data_protection" in
JSON::Validator::Schema for more details.
id
$str = $schema->id;
$schema = $schema->id($str);
Holds the ID for this schema. Usually extracted from "$id" or "id" in "data".
moniker
$str = $schema->moniker;
$schema = $schema->moniker("some_name");
Used to get/set the moniker for the given schema. Will be "draft04" if "specification" points to a JSON
Schema draft URL, and fallback to empty string if unable to guess a moniker name.
This attribute will (probably) detect more monikers from a given "specification" or "/id" in the future.
recursive_data_protection
$schema = $schema->recursive_data_protection($bool);
$bool = $schema->recursive_data_protection;
Recursive data protection is active by default, however it can be deactivated by assigning a false value
to the "recursive_data_protection" attribute.
Recursive data protection can have a noticeable impact on memory usage when validating large data
structures. If you are encountering issues with memory and you can guarantee that you do not have any
loops in your data structure then deactivating the recursive data protection may help.
This attribute is EXPERIMENTAL and may change in a future release.
Disclaimer: Use at your own risk, if you have any doubt then don't use it
specification
$str = $schema->specification;
$schema = $schema->specification($str);
The URL to the specification used when checking for "errors". Usually extracted from "$schema" or
"schema" in "data".
store
$store = $schema->store;
Holds a JSON::Validator::Store object that caches the retrieved schemas. This object can be shared
amongst different schema objects to prevent a schema from having to be downloaded again.
METHODS
bundle
$bundled = $schema->bundle;
$bundled is a new JSON::Validator::Schema object where none of the "$ref" will point to external
resources. This can be useful, if you want to have a bunch of files locally, but hand over a single file
to a client.
Mojo::File->new("client.json")
->spurt(Mojo::JSON::to_json($schema->bundle->data));
coerce
$schema = $schema->coerce('bool,def,num,str');
$schema = $schema->coerce('booleans,defaults,numbers,strings');
$hash_ref = $schema->coerce;
Set the given type to coerce. Before enabling coercion this module is very strict when it comes to
validating types. Example: The string "1" is not the same as the number 1, unless you have "numbers"
coercion enabled.
• booleans
Will convert what looks can be interpreted as a boolean (that is, an actual numeric 1 or 0, and the
strings "true" and "false") to a JSON::PP::Boolean object. Note that "foo" is not considered a true
value and will fail the validation.
• defaults
Will copy the default value defined in the schema, into the input structure, if the input value is non-
existing.
Note that support for "default" is currently EXPERIMENTAL, and enabling this might be changed in future
versions.
• numbers
Will convert strings that looks like numbers, into true numbers. This works for both the "integer" and
"number" types.
• strings
Will convert a number into a string. This works for the "string" type.
contains
This method will be removed in a future release.
data
my $hash_ref = $schema->data;
my $schema = $schema->data($bool);
my $schema = $schema->data($hash_ref);
Will set a structure representing the schema. In most cases you want to use "resolve" instead of "data".
get
my $data = $schema->get([@json_pointer]);
my $data = $schema->get($json_pointer);
my $data = $schema->get($json_pointer, sub { my ($data, $json_pointer) = @_; });
This method will extract data from "data", using a $json_pointer - RFC 6901
<http://tools.ietf.org/html/rfc6901>. It can however be used in a more complex way by passing in an
array-ref: The array-ref can contain "undef()" values, will result in extracting any element on that
point, regardsless of value. In that case a Mojo::Collection will be returned.
A callback can also be given. This callback will be called each time the $json_pointer matches some data,
and will pass in the $json_pointer at that place.
In addition if this method "sees" a JSON-Schema $ref on the way, the "$ref" will be followed into any
given sub schema.
is_invalid
my $bool = $schema->is_invalid;
Returns true if the schema in "data" is invalid. Internally this method calls "errors" which will
validate "data" agains "specification".
load_and_validate_schema
This method is unsupported. Use "is_invalid" or "errors" instead.
new
my $schema = JSON::Validator::Schema->new($data);
my $schema = JSON::Validator::Schema->new($data, %attributes);
my $schema = JSON::Validator::Schema->new(%attributes);
Construct a new JSON::Validator::Schema object. Passing on $data as the first argument will cause
"resolve" to be called, meaning the constructor might throw an exception if the schema could not be
successfully resolved.
resolve
$schema = $schema->resolve($uri);
$schema = $schema->resolve($data);
Used to resolve $uri or $data and store the resolved schema in "data". If $data or $uri contains any
$ref's, then these schemas will be downloaded and resolved as well.
If "data" does not contain an "id" or "$id", then "id" will be assigned a autogenerated "urn". This "urn"
might be changed in future releases, but should always be the same for the same "data".
schema
This method will be removed in a future release.
validate
@errors = $schema->validate($any);
Will validate $any against the schema defined in "data". Each element in @errors is an
JSON::Validator::Error object.
SEE ALSO
JSON::Validator.