JSON::...Result(3pm)

📦
version 0.642 · 4 versions
, in ubuntu stonking

✨ NAME ✨

JSON::Schema::Modern::Result — bestie, this is the lil container that holds the result of a JSON Schema evaluation 💖

So like, when you run a schema against your data and you're like "did it pass?? what went wrong??" — this object is what slides into your DMs with the receipts.

🌸 VERSION 🌸

version 0.642

I use a linearly-increasing version numbering scheme. No meaning should be presumed or inferred from the version being less than 1.0.

(translation: don't come for me about the 0.642 thing, the number is just a number, it's not a vibe check on maturity, ok?? 😭)

🎀 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->valid ? '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. It's the whole shebang, no crumbs left behind. 💅

👑 OVERLOADS 👑

The object contains a string overload, which evaluates to a potentially multi-line string summarizing the errors within (if any); this is intended to be used as a user-oriented error message that references data locations, but not schema locations. So it's the "hey bestie, something's off and here's roughly where" version, not the "here's the exact schema path, go read the spec" version.

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. Two results, one object, they ate and left no crumbs. 🫶

💜 CONSTRUCTOR ARGUMENTS 💜

Unless otherwise noted, these are also available as read-only accessors.

valid

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

Optional, as it can be calculated from the presence of errors or annotations. (so like, if you're lazy, the object can figure it out itself, no cap)

errors

An array of JSON::Schema::Modern::Error objects. 💀

annotations

An array of JSON::Schema::Modern::Annotation objects. 🌸

output_format

Also available as a read/write accessor.

One of: flag, basic, strict_basic, terse, data_only. Defaults to basic.

  • flag returns just the result of the evaluation: either {"valid": true} or {"valid": false}. Absolute bare minimum, it's giving minimalism. 💅
  • 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. (yes bestie, we're faithfully reproducing a bug on purpose, the spec said so 🙈)
  • 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). Less yapping, same tea. 🍓
  • 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. (so like, it's the experimental fit, it might get a glow-up later, don't build your whole personality on it being frozen 😌)

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. Like the whole thing face-planted. 😭

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' ]. Slay, it tells you exactly what to send back. 🔥

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'.

bestie, keep your internals private, that's the whole point of the 500 hiding ok 💀

Also available as a read/write accessor.

defaults

A hashref, mapping json pointer locations in the instance data to the default value assigned to the property at this location, taken from default keywords in the schema under properties and patternProperties keywords (requires the defaults in JSON::Schema::Modern configuration to be enabled). This data will also be included in the basic output format when it is defined. 🎀

data

Contains a cloned copy of the instance data that was evaluated; includes decoded values from contentEncoding and contentMediaType keywords, and is also populated with defaults if defaults is set (via with_defaults in JSON::Schema::Modern).

In results coming from OpenAPI::Modern, this value may contain deserialized data from various parts of the HTTP message, such as path and query parameters, header values, and the deserialized message body. Refer to that documentation for more details. 🦋

⭐ 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. She does what she's told. 💅

count

Returns the number of annotations when the result is true, or the number of errors when the result is false. One number, two moods. 🌈

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 draft2019-09 specification <https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10> and the draft2020-12 specification <https://json-schema.org/draft/2020-12/json-schema-core#section-12>.

🧚 SERIALIZATION 🧚

Results (and their contained errors and annotations) can be serialized in a number of ways. Pick your fighter bestie 💖

Results have defined output_formats, 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. 🎀

💖 GIVING THANKS 💖

If you found this module to be useful, please show your appreciation by adding a +1 in MetaCPAN <https://metacpan.org/dist/JSON-Schema-Modern> and a star in GitHub <https://github.com/karenetheridge/JSON-Schema-Modern>. Honestly it costs zero dollars and it makes someone's whole week, do it. ⭐

🌸 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. Come say hi, the group chat is open 🫶

🌟 AUTHOR 🌟

Karen Etheridge <ether@cpan.org>

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.

Some schema files have their own licence, in share/LICENSE. (yes babe, check before you redistribute, that's the rule 💅)

okay that's the whole page — perl v5.40.1, dated 2026-07-31, and this was JSON::Schema::Modern::Result(3pm) 💖 go forth and validate, bestie, you're gonna slay 🎀✨

📦 where this page comes from