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 file from web, if the $store has already retrieved
         # 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 associated
       values hold code blocks which can validate the 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 could 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 look 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, regardless 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" against "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 $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
       contain any "$ref", 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.