NAME

       JSON::Schema::Modern::Result - Contains the result of a JSON Schema evaluation

VERSION

       version 0.582

SYNOPSIS

         use JSON::Schema::Modern;
         my $js = JSON::Schema::Modern->new;
         my $result = $js->evaluate($data, $schema);
         my @errors = $result->errors;

         my $result_data_encoded = encode_json($result); # calls TO_JSON

         # use in numeric and boolean context
         say sprintf('got %d %ss', $result, ($result ? 'annotation' : 'error'));

         # use in string context
         say 'full results: ', $result;

         # combine two results into one:
         my $overall_result = $result1 & $result2;

DESCRIPTION

       This object holds the complete results of evaluating a data payload against a JSON Schema
       using JSON::Schema::Modern.

OVERLOADS

       The object contains a boolean overload, which evaluates to the value of "valid", so you
       can use the result of "evaluate" in JSON::Schema::Modern in boolean context.

       The object also contains a bitwise AND overload ("&"), for combining two results into one
       (the result is valid iff both inputs are valid; annotations and errors from the second
       argument are appended to those of the first in a new Result object).

ATTRIBUTES

   valid
       A boolean. Indicates whether validation was successful or failed.

   errors
       Returns an array of JSON::Schema::Modern::Error objects.

   annotations
       Returns an array of JSON::Schema::Modern::Annotation objects.

   output_format
       One of: "flag", "basic", "strict_basic", "detailed", "verbose", "terse", "data_only".
       Defaults to "basic".

       •   "flag" returns just the result of the evaluation: either "{"valid": true}" or
           "{"valid": false}".

       •   "basic" adds the list of "errors" or "annotations" to the boolean evaluation result.

           "instance_location" and "keyword_location" are always included, as JSON pointers,
           describing the path to the evaluation location; "absolute_keyword_location" is added
           (as a resolved URI) whenever it is known and different from "keyword_location".

       •   "strict_basic" is like "basic" but follows the draft-2019-09 specification precisely,
           including

           replicating an error fixed in the next draft, in that "instance_location" and
           "keyword_location" values are provided as fragment-only URI references rather than
           JSON pointers.

       •   "terse" is not described in any specification; it is like "basic", but omits some
           redundant

           errors (for example the one for the "allOf" keyword that is added when any of the
           subschemas under "allOf" failed evaluation).

       •   "data_only" returns a string, not a data structure: it contains a list of errors
           identified only

           by their "instance_location" and error message (or "keyword_location", when the error
           occurred while loading the schema itself). This format is suitable for generating
           errors when the schema is not published, or for describing errors with the schema
           itself. This is not an official specification format and may change slightly over
           time, as it is tested in production environments.

   formatted_annotations
       A boolean flag indicating whether "format" should include annotations in the output.
       Defaults to true.

   exception
       Indicates that evaluation stopped due to a severe error.

   recommended_response
       A tuple, consisting of "[ integer, string ]", indicating the recommended HTTP response
       code and string to use for this result (if validating an HTTP request). This could exist
       for things like a failed authentication check in OpenAPI validation, in which case it
       would contain "[ 401, 'Unauthorized' ]".

       Only populated when there are errors; when not explicitly set by an evaluator, defaults to
       "[ 500, 'Internal Server Error' ]" if any errors indicate an exception, and "[ 400, <first
       error string> ]" otherwise. The exact error string is hidden in the case of 500 errors
       because you should not leak internal issues with your application, but you may also wish
       to obfuscate normal validation errors, in which case you should check for 400 and change
       the string to 'Bad Request'.

METHODS

   format
       Returns a data structure suitable for serialization; requires one argument specifying the
       output format to use, which corresponds to the formats documented in
       <https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10.4>. The only
       supported formats at this time are "flag", "basic", "strict_basic", and "terse".

   TO_JSON
       Calls "format" with the style configured in "output_format".

   count
       Returns the number of annotations when the result is true, or the number of errors when
       the result is false.

   combine
       When provided with another result object, returns a new object with the combination of all
       results.  See "&" at "OVERLOADS".

   dump
       Returns a JSON string representing the result object, using the requested "format",
       according to the specification <https://json-schema.org/draft/2019-09/json-schema-
       core.html#rfc.section.10>.

SERIALIZATION

       Results (and their contained errors and annotations) can be serialized in a number of
       ways.

       Results have defined "output_format"s, which can be generated as nested unblessed
       hashes/arrays and are suitable for serializing using a JSON encoder for use in another
       application. A JSON string of the result can be obtained directly using "dump".

       If it is preferable to omit direct references to the schema (for example in an application
       where the schema is not published), but still convey some semantic information about the
       nature of the errors, stringify the object directly. This also means that result objects
       can be thrown as exceptions, or embedded in error messages.

       If you are embedding the full result inside another data structure, perhaps to be
       serialized to JSON (or another format) later on, use "TO_JSON" or "format".

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.