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

cpanm JSON::Validator

perl -MCPAN -e shell
install JSON::Validator