jammy (3) JSON::Validator::Schema.3pm.gz

Provided by: libjson-validator-perl_5.05+dfsg-1_all bug

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.