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.

ATTRIBUTES

errors

my $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.

id

my $str    = $schema->id;
my $schema = $schema->id($str);

Holds the ID for this schema. Usually extracted from "$id" or "id" in "data".

moniker

$str    = $schema->moniker;
$schema = $self->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.

specification

my $str    = $schema->specification;
my $schema = $schema->specification($str);

The URL to the specification used when checking for "errors". Usually extracted from "$schema" or "schema" in "data".

store

$store = $jv->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

my $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

my $schema   = $schema->coerce("booleans,defaults,numbers,strings");
my $schema   = $schema->coerce({booleans => 1});
my $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. Note that it will also change the internal data-structure of the validated data: Example:

$schema->coerce({numbers => 1});
$schema->data({properties => {age => {type => "integer"}}});

my $input = {age => "42"};
$schema->validate($input);
# $input->{age} is now an integer 42 and not the string "42"

contains

See "contains" in Mojo::JSON::Pointer.

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. 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 will be removed in a future release.

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