Provided by: libjson-schema-modern-perl_0.582-2_all bug

NAME

       JSON::Schema::Modern - Validate data against a schema

VERSION

       version 0.582

SYNOPSIS

         use JSON::Schema::Modern;

         $js = JSON::Schema::Modern->new(
           specification_version => 'draft2020-12',
           output_format => 'flag',
           ... # other options
         );
         $result = $js->evaluate($instance_data, $schema_data);

DESCRIPTION

       This module aims to be a fully-compliant JSON Schema <https://json-schema.org/> evaluator
       and validator, targeting the currently-latest Draft 2020-12 <https://json-
       schema.org/specification-links.html#2020-12> version of the specification.

CONFIGURATION OPTIONS

       These values are all passed as arguments to the constructor.

   specification_version
       Indicates which version of the JSON Schema specification is used during evaluation. When
       not set, this value is derived from the $schema keyword in the schema used in evaluation,
       or defaults to the latest version (currently "draft2020-12").

       The use of this option is HIGHLY encouraged to ensure continued correct operation of your
       schema.  The current default value will not stay the same over time.

       May be one of:

       •   "draft2020-12" or "2020-12" <https://json-schema.org/specification-
           links.html#2020-12>, corresponding to metaschema
           "https://json-schema.org/draft/2020-12/schema"

       •   "draft2019-09" or "2019-09" <https://json-schema.org/specification-
           links.html#2019-09-formerly-known-as-draft-8>, corresponding to metaschema
           "https://json-schema.org/draft/2019-09/schema"

       •   "draft7" or 7 <https://json-schema.org/specification-links.html#draft-7>,
           corresponding to metaschema "http://json-schema.org/draft-07/schema#"

       Note that you can also use a $schema keyword in the schema itself, to specify a different
       metaschema or specification version.

   output_format
       One of: "flag", "basic", "strict_basic", "detailed", "verbose", "terse". Defaults to
       "basic".  "strict_basic" can only be used with "specification_version = draft2019-09".
       Passed to "output_format" in JSON::Schema::Modern::Result.

   short_circuit
       When true, evaluation will return early in any execution path as soon as the outcome can
       be determined, rather than continuing to find all errors or annotations.  This option is
       safe to use in all circumstances, even in the presence of "unevaluatedItems" and
       "unevaluatedProperties" keywords: the validation result will not change; only some errors
       will be omitted from the result.

       Defaults to true when "output_format" is "flag", and false otherwise.

   max_traversal_depth
       The maximum number of levels deep a schema traversal may go, before evaluation is halted.
       This is to protect against accidental infinite recursion, such as from two subschemas that
       each reference each other, or badly-written schemas that could be optimized. Defaults to
       50.

   validate_formats
       When true, the "format" keyword will be treated as an assertion, not merely an annotation.
       Defaults to true when specification_version is draft7, and false for all other versions,
       but this may change in the future.

       Note that the use of a format that does not have a defined handler will not be interpreted
       as an error in this mode; instead, the undefined format will simply be ignored. If you
       instead want this to be treated as an evaluation error, you must define a custom schema
       dialect that uses the format-assertion vocabulary (available in specification version
       "draft2020-12") and reference it in your schema with the $schema keyword.

   format_validations
       An optional hashref that allows overriding the validation method for formats, or adding
       new ones.  Overrides to existing formats (see "Format Validation") must be specified in
       the form of "{ $format_name => $format_sub }", where the format sub is a subref that takes
       one argument and returns a boolean result. New formats must be specified in the form of "{
       $format_name => { type => $type, sub => $format_sub } }", where the type indicates which
       of the core JSON Schema types (null, object, array, boolean, string, number, or integer)
       the instance value must be for the format validation to be considered.

   validate_content_schemas
       When true, the "contentMediaType" and "contentSchema" keywords are not treated as pure
       annotations: "contentEncoding" (when present) is used to decode the applied data payload
       and then "contentMediaType" will be used as the media-type for decoding to produce the
       data payload which is then applied to the schema in "contentSchema" for validation. (Note
       that treating these keywords as anything beyond simple annotations is contrary to the
       specification, therefore this option defaults to false.)

       See "add_media_type" and "add_encoding" for adding additional type support.

       Technically only draft7 allows this and drafts 2019-09 and 2020-12 prohibit ever returning
       the subschema evaluation results together with their parent schema's results, so shhh. I'm
       trying to get this fixed for the next draft.

   collect_annotations
       When true, annotations are collected from keywords that produce them, when validation
       succeeds.  These annotations are available in the returned result (see
       JSON::Schema::Modern::Result).  Not operational when "specification_version" is "draft7".
       Defaults to false.

   scalarref_booleans
       When true, any value that is expected to be a boolean in the instance data may also be
       expressed as the scalar references "\0" or "\1" (which are serialized as booleans by JSON
       backends).

       Defaults to false.

   stringy_numbers
       When true, any value that is expected to be a number or integer in the instance data may
       also be expressed as a string. This applies only to the following keywords:

       •   "type" (where both "string" and "number" (and possibly "integer") are considered
           valid)

       •   "const" and "enum" (where the string "1" will match with ""const": 1")

       •   "uniqueItems" (where strings and numbers are compared numerically to each other, if
           either or both are numeric)

       •   "multipleOf"

       •   "maximum"

       •   "exclusiveMaximum"

       •   "minimum"

       •   "exclusiveMinimum"

       •   "format" (for formats defined to validate numbers)

       This allows you to write a schema like this (which validates a string representing an
       integer):

         type: string
         pattern: ^[0-9]$
         multipleOf: 4
         minimum: 16
         maximum: 256

       Such keywords are only applied if the value looks like a number, and do not generate a
       failure otherwise. Values are determined to be numbers via "looks_like_number" in perlapi.
       This option is only intended to be used for evaluating data from sources that can only be
       strings, such as the extracted value of an HTTP header or query parameter.

       Defaults to false.

   strict
       When true, unrecognized keywords are disallowed in schemas (they will cause an immediate
       abort in "traverse" or "evaluate").

       Defaults to false.

METHODS

   evaluate_json_string
         $result = $js->evaluate_json_string($data_as_json_string, $schema);
         $result = $js->evaluate_json_string($data_as_json_string, $schema, { collect_annotations => 1});

       Evaluates the provided instance data against the known schema document.

       The data is in the form of a JSON-encoded string (in accordance with RFC8259
       <https://datatracker.ietf.org/doc/html/rfc8259>). The string is expected to be UTF-8
       encoded.

       The schema must be in one of these forms:

       •   a Perl data structure, such as what is returned from a JSON decode operation,

       •   a JSON::Schema::Modern::Document object,

       •   or a URI string indicating the location where such a schema is located.

       Optionally, a hashref can be passed as a third parameter which allows changing the values
       of the "short_circuit", "collect_annotations", "scalarref_booleans", "stringy_numbers",
       "strict", "validate_formats", and/or "validate_content_schemas" settings for just this
       evaluation call.

       You can also pass use these keys to alter behaviour (these are generally only used by
       custom validation applications that contain embedded JSON Schemas):

       •   "data_path": adjusts the effective path of the data instance as of the start of
           evaluation

       •   "traversed_schema_path": adjusts the accumulated path as of the start of evaluation
           (or last $id or $ref)

       •   "initial_schema_uri": adjusts the recorded absolute keyword location as of the start
           of evaluation

       •   "effective_base_uri": locations in errors and annotations are resolved against this
           URI

       The return value is a JSON::Schema::Modern::Result object, which can also be used as a
       boolean.

   evaluate
         $result = $js->evaluate($instance_data, $schema);
         $result = $js->evaluate($instance_data, $schema, { short_circuit => 0 });

       Evaluates the provided instance data against the known schema document.

       The data is in the form of an unblessed nested Perl data structure representing any type
       that JSON allows: null, boolean, string, number, object, array. (See "Types" below.)

       The schema must be in one of these forms:

       •   a Perl data structure, such as what is returned from a JSON decode operation,

       •   a JSON::Schema::Modern::Document object,

       •   or a URI string indicating the location where such a schema is located.

       Optionally, a hashref can be passed as a third parameter which allows changing the values
       of the "short_circuit", "collect_annotations", "scalarref_booleans", "stringy_numbers",
       "strict", "validate_formats", and/or "validate_content_schemas" settings for just this
       evaluation call.

       You can also pass use these keys to alter behaviour (these are generally only used by
       custom validation applications that contain embedded JSON Schemas):

       •   "data_path": adjusts the effective path of the data instance as of the start of
           evaluation

       •   "traversed_schema_path": adjusts the accumulated path as of the start of evaluation
           (or last $id or $ref)

       •   "initial_schema_uri": adjusts the recorded absolute keyword location as of the start
           of evaluation

       •   "effective_base_uri": locations in errors and annotations are resolved against this
           URI

       You can pass a series of callback subs to this method corresponding to keywords, which is
       useful for identifying various data that are not exposed by annotations.  This feature is
       highly experimental and may change in the future.

       For example, to find the locations where all $ref keywords are applied successfully:

         my @used_ref_at;
         $js->evaluate($data, $schema_or_uri, {
           callbacks => {
             '$ref' => sub ($data, $schema, $state) {
               push @used_ref_at, $state->{data_path};
             }
           },
         });

       The return value is a JSON::Schema::Modern::Result object, which can also be used as a
       boolean.  Callbacks are not compatible with "short_circuit" mode.

   validate_schema
         $result = $js->validate_schema($schema);
         $result = $js->validate_schema($schema, $config_override);

       Evaluates the provided schema as instance data against its metaschema. Accepts $schema and
       $config_override parameters in the same form as "evaluate".

   traverse
         $result = $js->traverse($schema);
         $result = $js->traverse($schema, { initial_schema_uri => 'http://example.com' });

       Traverses the provided schema without evaluating it against any instance data. Returns the
       internal state object accumulated during the traversal, including any identifiers found
       therein, and any errors found during parsing. For internal purposes only.

       Optionally, a hashref can be passed as a second parameter which alters some behaviour
       (these are generally only used by custom validation applications that contain embedded
       JSON Schemas):

       •   "traversed_schema_path": adjusts the accumulated path as of the start of evaluation
           (or last $id or $ref)

       •   "initial_schema_uri": adjusts the recorded absolute keyword location as of the start
           of evaluation

       •   "metaschema_uri": use the indicated URI as the metaschema

       You can pass a series of callback subs to this method corresponding to keywords, which is
       useful for extracting data from within schemas and skipping properties that may look like
       keywords but actually are not (for example "{"const": {"$ref": "this is not actually a
       $ref"}}"). This feature is highly experimental and is highly likely to change in the
       future.

       For example, to find the resolved targets of all $ref keywords in a schema document:

         my @refs;
         JSON::Schema::Modern->new->traverse($schema, {
           callbacks => {
             '$ref' => sub ($schema, $state) {
               push @refs, Mojo::URL->new($schema->{'$ref'})
                 ->to_abs(JSON::Schema::Modern::Utilities::canonical_uri($state));
             }
           },
         });

   add_schema
         $js->add_schema($uri => $schema);
         $js->add_schema($uri => $document);
         $js->add_schema($schema);
         $js->add_schema($document);

       Introduces the (unblessed, nested) Perl data structure or JSON::Schema::Modern::Document
       object, representing a JSON Schema, to the implementation, registering it under the
       indicated URI if provided (and if not, '' will be used if no other identifier can be found
       within).

       You MUST call "add_schema" for any external resources that a schema may reference via $ref
       before calling "evaluate", other than the standard metaschemas which are loaded from a
       local cache as needed.

       Returns "undef" if the resource could not be found; if there were errors in the document,
       will die with these errors; otherwise returns the JSON::Schema::Modern::Document that
       contains the added schema.

   add_format_validation
         $js->add_format_validation(all_lc => sub ($value) { lc($value) eq $value });

       or

         $js->add_format_validation(no_nines => { type => 'number', sub => sub ($value) { $value =~ m/^[0-8]$$/ });

       Adds support for a custom format. If not supplied, the data type(s) that this format
       applies to defaults to string; all values of any other type will automatically be deemed
       to be valid, and will not be passed to the subref.

       Additionally, you can redefine the definition for any core format (see "Format
       Validation"), but the data type(s) supported by that format may not be changed.

       Be careful to not mutate the type of the value while checking it -- for example, if it is
       a string, do not apply arithmetic operators to it -- or subsequent type checks on this
       value may fail.

   add_vocabulary
         $js->add_vocabulary('My::Custom::Vocabulary::Class');

       Makes a custom vocabulary class available to metaschemas that make use of this vocabulary.
       as described in the specification at "Meta-Schemas and Vocabularies" <https://json-
       schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.1>.

       The class must compose the JSON::Schema::Modern::Vocabulary role and implement the
       vocabulary and keywords methods, as well as "_traverse_keyword_<keyword name>" methods for
       each keyword. "_eval_keyword_<keyword name>" methods are optional; when not provided,
       evaluation will always return a true result.

   add_media_type
         $js->add_media_type('application/furble' => sub ($content_ref) {
           return ...;  # data representing the deserialized text for Content-Type: application/furble
         });

       Takes a media-type name and a subref which takes a single scalar reference, which is
       expected to be a reference to a string, which might contain wide characters (i.e. not
       octets), especially when used in conjunction with "get_encoding" below. Must return a
       reference to a value of any type (which is then dereferenced for the "contentSchema"
       keyword).

       These media types are already known:

       •   "application/json" - see RFC 4627 <https://datatracker.ietf.org/doc/html/rfc4627>

       •   "application/schema+json" - see proposed definition <https://json-
           schema.org/draft/2020-12/json-schema-core.html#name-application-schemajson>

       •   "application/schema-instance+json" - see proposed definition <https://json-
           schema.org/draft/2020-12/json-schema-core.html#name-application-schema-instance>

       •   "application/octet-stream" - passes strings through unchanged

       •   "application/x-www-form-urlencoded"

       •   "application/x-ndjson" - see <https://github.com/ndjson/ndjson-spec>

       •   "text/*" - passes strings through unchanged

   get_media_type
       Fetches a decoder sub for the indicated media type. Lookups are performed without case
       sensitivity.

       You can use it thusly:

         $js->add_media_type('application/furble' => sub { ... }); # as above
         my $decoder = $self->get_media_type('application/furble') or die 'cannot find media type decoder';
         my $content_ref = $decoder->(\$content_string);

   add_encoding
         $js->add_encoding('bloop' => sub ($content_ref) {
           return \ ...;  # data representing the deserialized content for Content-Transfer-Encoding: bloop
         });

       Takes an encoding name and a subref which takes a single scalar reference, which is
       expected to be a reference to a string, which SHOULD be a 7-bit or 8-bit string. Result
       values MUST be a scalar-reference to a string (which is then dereferenced for the
       "contentMediaType" keyword).

       Encodings handled natively are:

       •   "identity" - passes strings through unchanged

       •   "base64" - see RFC 4648 §4 <https://datatracker.ietf.org/doc/html/rfc4648#section-4>

       •   "base64url" - see RFC 4648 §5
           <https://datatracker.ietf.org/doc/html/rfc4648#section-5>

       See also "encode" in HTTP::Message.

   get_encoding
       Fetches a decoder sub for the indicated encoding. Incoming values MUST be a reference to
       an octet string. Result values will be a scalar-reference to a string, which might be
       passed to a media_type decoder (see above).

       You can use it thusly:

         my $decoder = $self->get_encoding('base64') or die 'cannot find encoding decoder';
         my $content_ref = $decoder->(\$content_string);

   get
         my $schema = $js->get($uri);
         my ($schema, $canonical_uri) = $js->get($uri);

       Fetches the Perl data structure representing the JSON Schema at the indicated identifier
       (uri or uri-reference). When called in list context, the canonical URI of that location is
       also returned, as a Mojo::URL. Returns "undef" if the schema with that URI has not been
       loaded (or cached).

   get_document
         my $document = $js->get_document($uri_reference);

       Fetches the JSON::Schema::Modern::Document object that contains the provided identifier
       (uri or uri-reference). "undef" if the schema with that URI has not been loaded (or
       cached).

LIMITATIONS

   Types
       Perl is a more loosely-typed language than JSON. This module delves into a value's
       internal representation in an attempt to derive the true "intended" type of the value.
       However, if a value is used in another context (for example, a numeric value is
       concatenated into a string, or a numeric string is used in an arithmetic operation),
       additional flags can be added onto the variable causing it to resemble the other type.
       This should not be an issue if data validation is occurring immediately after decoding a
       JSON payload, or if the JSON string itself is passed to this module.  If you are still
       having difficulties, make sure you are using Perl's fastest and most trusted and reliable
       JSON decoder, Cpanel::JSON::XS.  Other JSON decoders are known to produce data with
       incorrect data types.

       For more information, see "MAPPING" in Cpanel::JSON::XS.

   Format Validation
       By default (and unless you specify a custom metaschema with the $schema keyword or
       "metaschema" in JSON::Schema::Modern::Document), formats are treated only as annotations,
       not assertions. When "validate_formats" is true, strings are also checked against the
       format as specified in the schema. At present the following formats are supported (use of
       any other formats than these will always evaluate as true, but remember you can always
       supply custom format handlers; see "format_validations" above):

       •   "date-time"

       •   "date"

       •   "time"

       •   "duration"

       •   "email"

       •   "idn-email"

       •   "hostname"

       •   "idn-hostname"

       •   "ipv4"

       •   "ipv6"

       •   "uri"

       •   "uri-reference"

       •   "iri"

       •   "uuid"

       •   "json-pointer"

       •   "relative-json-pointer"

       •   "regex"

       A few optional prerequisites are needed for some of these (if the prerequisite is missing,
       validation will always succeed):

       •   "date-time", "date", and "time" require Time::Moment, DateTime::Format::RFC3339

       •   "email" and "idn-email" require Email::Address::XS version 1.04 (or higher)

       •   "hostname" and "idn-hostname" require Data::Validate::Domain

       •   "idn-hostname" requires Net::IDN::Encode

   Specification Compliance
       This implementation is now fully specification-compliant (for versions draft7,
       draft2019-09, draft2020-12), but until version 1.000 is released, it is still deemed to be
       missing some optional but quite useful features, such as:

       •   loading schema documents from disk

       •   loading schema documents from the network

       •   loading schema documents from a local web application (e.g. Mojolicious)

       •   additional output formats beyond "flag", "basic", and "terse"
           (<https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.12>)

SECURITY CONSIDERATIONS

       The "pattern" and "patternProperties" keywords evaluate regular expressions from the
       schema, the "regex" format validator evaluates regular expressions from the data, and some
       keywords in the Validation vocabulary perform floating point operations on potentially-
       very large numbers.  No effort is taken (at this time) to sanitize the regular expressions
       for embedded code or detect potentially pathological constructs that may pose a security
       risk, either via denial of service or by allowing exposure to the internals of your
       application. DO NOT USE SCHEMAS FROM UNTRUSTED SOURCES.

       (In particular, see vulnerability
       "CVE-2023-47038-Write-past-buffer-end-via-illegal-user-defined-Unicode-property" in
       perl5363delta, which is closed in Perl releases 5.34.3, 5.36.3 and 5.38.1.)

SEE ALSO

       •   json-schema-eval

       •   <https://json-schema.org>

       •   RFC8259: The JavaScript Object Notation (JSON) Data Interchange Format
           <https://datatracker.ietf.org/doc/html/rfc8259>

       •   RFC3986: Uniform Resource Identifier (URI): Generic Syntax
           <https://datatracker.ietf.org/doc/html/rfc3986>

       •   Test::JSON::Schema::Acceptance: contains the official JSON Schema test suite

       •   JSON::Schema::Tiny: a more stripped-down implementation of the specification, with
           fewer dependencies and faster evaluation

       •   <https://json-schema.org/draft/2020-12/release-notes.html>

       •   <https://json-schema.org/draft/2019-09/release-notes.html>

       •   <https://json-schema.org/draft-07/json-schema-release-notes.html>

       •   Understanding JSON Schema <https://json-schema.org/understanding-json-schema>:
           tutorial-focused documentation

       •   OpenAPI::Modern: a parser and evaluator for OpenAPI v3.1 documents

       •   Mojolicious::Plugin::OpenAPI::Modern: a Mojolicious plugin providing OpenAPI
           functionality

       •   Test::Mojo::Role::OpenAPI::Modern: test your Mojolicious application's OpenAPI
           compliance

SUPPORT

       Bugs may be submitted through
       <https://github.com/karenetheridge/JSON-Schema-Modern/issues>.

       I am also usually active on irc, as 'ether' at "irc.perl.org" and "irc.libera.chat".

       You can also find me on the JSON Schema Slack server <https://json-schema.slack.com> and
       OpenAPI Slack server <https://open-api.slack.com>, which are also great resources for
       finding help.

AUTHOR

       Karen Etheridge <ether@cpan.org>

COPYRIGHT AND LICENCE

       This software is copyright (c) 2020 by Karen Etheridge.

       This is free software; you can redistribute it and/or modify it under the same terms as
       the Perl 5 programming language system itself.