.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "JSON::Validator::Schema 3pm"
.TH JSON::Validator::Schema 3pm "2023-03-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
JSON::Validator::Schema \- Base class for JSON::Validator schemas
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.SS "Basics"
.IX Subsection "Basics"
.Vb 4
\&  # 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(\*(Aqfile:///cool/beans.yaml\*(Aq);
\&
\&  # Validate the schema
\&  die $schema\->errors\->[0] if $schema\->is_invalid;
\&
\&  # Validate data
\&  my @errors = $schema\->validate({some => \*(Aqdata\*(Aq});
\&  die $errors[0] if @errors;
.Ve
.SS "Shared store"
.IX Subsection "Shared store"
.Vb 2
\&  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(\*(Aqhttps://api.example.com/cool/beans.json\*(Aq);
.Ve
.SS "Make a new validation class"
.IX Subsection "Make a new validation class"
.Vb 4
\&  package JSON::Validator::Schema::SomeSchema;
\&  use Mojo::Base \*(AqJSON::Validator::Schema\*(Aq;
\&  has specification => \*(Aqhttps://api.example.com/my/spec.json#\*(Aq;
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
Any of the classes above can be used instead of JSON::Validator if you know
which draft/version you are working with up front.
.SS "Validation"
.IX Subsection "Validation"
JSON::Validator::Schema can both validate user input and the schema itself.
.IP "\(bu" 2
A JSON::Validator::Schema represents a set of validation rules stored in
\&\*(L"data\*(R". The rules stored in the \*(L"data\*(R" attribute will be used when calling
the \*(L"validate\*(R" method.
.IP "\(bu" 2
The input to \f(CW\*(C`validate()\*(C'\fR could be some data from a web request or some other
user input. \f(CW\*(C`validate()\*(C'\fR returns a list of JSON::Validator::Error objects,
if the user input (input to \f(CW\*(C`validate()\*(C'\fR) contains invalid data.
.IP "\(bu" 2
The \*(L"errors\*(R" and \*(L"is_invalid\*(R" attributes has nothing to do with user input,
meaning it is \fInot\fR relevant for \*(L"validate\*(R". These two accessors are used to
check if the rules/schema stored in \*(L"data\*(R" is correct. The validation is
performed against the \*(L"specification\*(R". This is pretty much the same as:
.Sp
.Vb 4
\&  my $jv = JSON::Validator\->new;
\&  my $draft7 = $jv\->schema(\*(Aqhttp://json\-schema.org/draft\-07/schema#\*(Aq)\->schema;
\&  my $schema = $jv\->schema({name => {type => \*(Aqstring\*(Aq}})\->schema;
\&  my @errors = $draft7\->validate($schema\->data);
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.SS "errors"
.IX Subsection "errors"
.Vb 1
\&  $array_ref = $schema\->errors;
.Ve
.PP
Holds the errors after checking \*(L"data\*(R" against \*(L"specification\*(R".
\&\f(CW$array_ref\fR containing no elements means \*(L"data\*(R" is valid. Each element in
the array-ref is a JSON::Validator::Error object.
.PP
This attribute is \fInot\fR changed by \*(L"validate\*(R". It only reflects if the
\&\f(CW$schema\fR is valid.
.SS "formats"
.IX Subsection "formats"
.Vb 2
\&  $hash_ref = $schema\->formats;
\&  $schema   = $schema\->formats(\e%hash);
.Ve
.PP
Holds a hash-ref, where the keys are supported \s-1JSON\s0 type \*(L"formats\*(R", and
the associated values hold code blocks which can validate the given format.
A code block should return \f(CW\*(C`undef\*(C'\fR on success and an error string on error:
.PP
.Vb 1
\&  sub { return defined $_[0] && $_[0] eq "42" ? undef : "Not the answer." };
.Ve
.PP
See JSON::Validator::Formats for a list of supported formats.
.SS "recursive_data_protection"
.IX Subsection "recursive_data_protection"
The value of this attribute will be copied into the created \*(L"schema\*(R".  See
\&\*(L"recursive_data_protection\*(R" in JSON::Validator::Schema for more details.
.SS "id"
.IX Subsection "id"
.Vb 2
\&  $str    = $schema\->id;
\&  $schema = $schema\->id($str);
.Ve
.PP
Holds the \s-1ID\s0 for this schema. Usually extracted from \f(CW"$id"\fR or \f(CW"id"\fR in
\&\*(L"data\*(R".
.SS "moniker"
.IX Subsection "moniker"
.Vb 2
\&  $str    = $schema\->moniker;
\&  $schema = $schema\->moniker("some_name");
.Ve
.PP
Used to get/set the moniker for the given schema. Will be \*(L"draft04\*(R" if
\&\*(L"specification\*(R" points to a \s-1JSON\s0 Schema draft \s-1URL,\s0 and fallback to
empty string if unable to guess a moniker name.
.PP
This attribute will (probably) detect more monikers from a given
\&\*(L"specification\*(R" or \f(CW\*(C`/id\*(C'\fR in the future.
.SS "recursive_data_protection"
.IX Subsection "recursive_data_protection"
.Vb 2
\&  $schema = $schema\->recursive_data_protection($bool);
\&  $bool   = $schema\->recursive_data_protection;
.Ve
.PP
Recursive data protection is active by default, however it can be deactivated
by assigning a false value to the \*(L"recursive_data_protection\*(R" attribute.
.PP
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.
.PP
This attribute is \s-1EXPERIMENTAL\s0 and may change in a future release.
.PP
\&\fBDisclaimer: Use at your own risk, if you have any doubt then don't use it\fR
.SS "specification"
.IX Subsection "specification"
.Vb 2
\&  $str    = $schema\->specification;
\&  $schema = $schema\->specification($str);
.Ve
.PP
The \s-1URL\s0 to the specification used when checking for \*(L"errors\*(R". Usually
extracted from \f(CW"$schema"\fR or \f(CW"schema"\fR in \*(L"data\*(R".
.SS "store"
.IX Subsection "store"
.Vb 1
\&  $store = $schema\->store;
.Ve
.PP
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.
.SH "METHODS"
.IX Header "METHODS"
.SS "bundle"
.IX Subsection "bundle"
.Vb 1
\&  $bundled = $schema\->bundle;
.Ve
.PP
\&\f(CW$bundled\fR is a new JSON::Validator::Schema object where none of the \*(L"$ref\*(R"
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.
.PP
.Vb 2
\&  Mojo::File\->new("client.json")
\&    \->spurt(Mojo::JSON::to_json($schema\->bundle\->data));
.Ve
.SS "coerce"
.IX Subsection "coerce"
.Vb 3
\&  $schema   = $schema\->coerce(\*(Aqbool,def,num,str\*(Aq);
\&  $schema   = $schema\->coerce(\*(Aqbooleans,defaults,numbers,strings\*(Aq);
\&  $hash_ref = $schema\->coerce;
.Ve
.PP
Set the given type to coerce. Before enabling coercion this module is very
strict when it comes to validating types. Example: The string \f(CW"1"\fR is not the
same as the number \f(CW1\fR, unless you have \*(L"numbers\*(R" coercion enabled.
.IP "\(bu" 2
booleans
.Sp
Will convert what could be interpreted as a boolean (that is, an actual
numeric \f(CW1\fR or \f(CW0\fR, and the strings \*(L"true\*(R" and \*(L"false\*(R") to a
JSON::PP::Boolean object. Note that \*(L"foo\*(R" is not considered a true value and
will fail the validation.
.IP "\(bu" 2
defaults
.Sp
Will copy the default value defined in the schema, into the input structure,
if the input value is non-existing.
.Sp
Note that support for \*(L"default\*(R" is currently \s-1EXPERIMENTAL,\s0 and enabling this
might be changed in future versions.
.IP "\(bu" 2
numbers
.Sp
Will convert strings that look like numbers, into true numbers. This works for
both the \*(L"integer\*(R" and \*(L"number\*(R" types.
.IP "\(bu" 2
strings
.Sp
Will convert a number into a string. This works for the \*(L"string\*(R" type.
.SS "contains"
.IX Subsection "contains"
This method will be removed in a future release.
.SS "data"
.IX Subsection "data"
.Vb 3
\&  my $hash_ref = $schema\->data;
\&  my $schema   = $schema\->data($bool);
\&  my $schema   = $schema\->data($hash_ref);
.Ve
.PP
Will set a structure representing the schema. In most cases you want to
use \*(L"resolve\*(R" instead of \*(L"data\*(R".
.SS "get"
.IX Subsection "get"
.Vb 3
\&  my $data = $schema\->get([@json_pointer]);
\&  my $data = $schema\->get($json_pointer);
\&  my $data = $schema\->get($json_pointer, sub { my ($data, $json_pointer) = @_; });
.Ve
.PP
This method will extract data from \*(L"data\*(R", using a \f(CW$json_pointer\fR \-
\&\s-1RFC 6901\s0 <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 \f(CW\*(C`undef()\*(C'\fR
values, will result in extracting any element on that point, regardless of
value. In that case a Mojo::Collection will be returned.
.PP
A callback can also be given. This callback will be called each time the
\&\f(CW$json_pointer\fR matches some data, and will pass in the \f(CW$json_pointer\fR at
that place.
.PP
In addition if this method \*(L"sees\*(R" a JSON-Schema \f(CW$ref\fR on the way, the \*(L"$ref\*(R"
will be followed into any given sub-schema.
.SS "is_invalid"
.IX Subsection "is_invalid"
.Vb 1
\&  my $bool = $schema\->is_invalid;
.Ve
.PP
Returns true if the schema in \*(L"data\*(R" is invalid. Internally this method calls
\&\*(L"errors\*(R" which will validate \*(L"data\*(R" against \*(L"specification\*(R".
.SS "load_and_validate_schema"
.IX Subsection "load_and_validate_schema"
This method is unsupported. Use \*(L"is_invalid\*(R" or \*(L"errors\*(R" instead.
.SS "new"
.IX Subsection "new"
.Vb 3
\&  my $schema = JSON::Validator::Schema\->new($data);
\&  my $schema = JSON::Validator::Schema\->new($data, %attributes);
\&  my $schema = JSON::Validator::Schema\->new(%attributes);
.Ve
.PP
Construct a new JSON::Validator::Schema object. Passing \f(CW$data\fR as the
first argument will cause \*(L"resolve\*(R" to be called, meaning the constructor
might throw an exception if the schema could not be successfully resolved.
.SS "resolve"
.IX Subsection "resolve"
.Vb 2
\&  $schema = $schema\->resolve($uri);
\&  $schema = $schema\->resolve($data);
.Ve
.PP
Used to resolve \f(CW$uri\fR or \f(CW$data\fR and store the resolved schema in \*(L"data\*(R".
If \f(CW$data\fR or \f(CW$uri\fR contain any \*(L"$ref\*(R", then these schemas will be
downloaded and resolved as well.
.PP
If \*(L"data\*(R" does not contain an \*(L"id\*(R" or \*(L"$id\*(R", then \*(L"id\*(R" will be assigned a
autogenerated \*(L"urn\*(R". This \*(L"urn\*(R" might be changed in future releases, but should
always be the same for the same \*(L"data\*(R".
.SS "schema"
.IX Subsection "schema"
This method will be removed in a future release.
.SS "validate"
.IX Subsection "validate"
.Vb 1
\&  @errors = $schema\->validate($any);
.Ve
.PP
Will validate \f(CW$any\fR against the schema defined in \*(L"data\*(R". Each element in
\&\f(CW@errors\fR is an JSON::Validator::Error object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
JSON::Validator.