JSON::Schema::Draft201909 - Validate data against a schema
version 0.027
use JSON::Schema::Draft201909; $js = JSON::Schema::Draft201909->new( output_format => 'flag', ... # other options ); $result = $js->evaluate($instance_data, $schema_data);
This module aims to be a fully-compliant JSON Schema evaluator and validator, targeting the currently-latest Draft 2019-09 version of the specification.
One of: flag, basic, strict_basic, detailed, verbose, terse. Defaults to basic. Passed to "output_format" in JSON::Schema::Draft201909::Result.
flag
basic
strict_basic
detailed
verbose
terse
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. Be aware that this can result in invalid results in the presence of keywords that depend on annotations, namely unevaluatedItems and unevaluatedProperties.
unevaluatedItems
unevaluatedProperties
Defaults to true when output_format is flag, and false otherwise.
output_format
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.
When true, the format keyword will be treated as an assertion, not merely an annotation. Defaults to false.
format
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 coderef 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.
{ $format_name => $format_sub }
{ $format_name => { type => $type, sub => $format_sub } }
When true, annotations are collected from keywords that produce them, when validation succeeds. These annotations are available in the returned result (see JSON::Schema::Draft201909::Result). Defaults to false.
When true, keywords that are not recognized by any vocabulary are collected as annotations (where the value of the annotation is the value of the keyword). "collect_annotations" must also be true in order for this to have any effect. Defaults to false (for now).
$result = $js->evaluate_json_string($data_as_json_string, $schema_data); $result = $js->evaluate_json_string($data_as_json_string, $schema_data, { 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). The string is expected to be UTF-8 encoded.
The schema must represent a JSON Schema that respects the Draft 2019-09 meta-schema at https://json-schema.org/draft/2019-09/schema, in one of these forms:
a Perl data structure, such as what is returned from a JSON decode operation,
a JSON::Schema::Draft201909::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", "annotate_unknown_keywords" and/or "validate_formats" settings for just this evaluation call.
The result is a JSON::Schema::Draft201909::Result object, which can also be used as a boolean.
$result = $js->evaluate($instance_data, $schema_data); $result = $js->evaluate($instance_data, $schema_data, { short_circuit => 0 });
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.)
$result = $js->traverse($schema_data); $result = $js->traverse($schema_data, { canonical_schema_uri => 'http://example.com' });
Traverses the provided schema data 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.
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.
{"const":{"$ref": "this is not actually a $ref"}}
For example, to find the resolved targets of all $ref keywords in a schema document:
$ref
my @refs; JSON::Schema::Draft201909->new->traverse($schema, { callbacks => { '$ref' => sub ($schema, $state) { push @refs, Mojo::URL->new($schema->{'$ref'}) ->to_abs(JSON::Schema::Draft201909::Utilities::canonical_schema_uri($state)); } }, });
$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::Draft201909::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.
add_schema
Returns undef if the resource could not be found; if there were errors in the document, will die with a JSON::Schema::Draft201909::Result object containing the errors; otherwise returns the JSON::Schema::Draft201909::Document that contains the added schema.
undef
my $schema = $js->get($uri); my ($schema, $canonical_uri) = $js->get($uri);
Fetches the Perl data structure representing the JSON Schema at the indicated URI. 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).
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 this turns out to be an issue in real environments, I may have to implement a lax_scalars option.
lax_scalars
For more information, see "MAPPING" in Cpanel::JSON::XS.
By default, formats are treated only as annotations, not assertions. When "validate_format" 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):
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
email and idn-email require Email::Address::XS version 1.01 (or higher)
hostname and idn-hostname require Data::Validate::Domain
idn-hostname requires Net::IDN::Encode
Until version 1.000 is released, this implementation is not fully specification-compliant.
To date, missing features (some of which are optional, but still quite useful) include:
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, strict_basic, and terse (https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10)
examination of the $schema keyword for deviation from the standard metaschema, including changes to vocabulary behaviour
$schema
Additionally, some small errors in the specification (which have been fixed in the next draft specification version) are fixed here rather than implementing the precise but unintended behaviour, most notably in the use of json pointers rather than fragment-only URIs in instanceLocation and keywordLocation in annotations and errors. (Use the strict_basic "output_format" in JSON::Schema::Draft201909 to revert this change.)
instanceLocation
keywordLocation
The pattern and patternProperties keywords, and the regex format validator, evaluate regular expressions from the schema. No effort is taken (at this time) to sanitize the regular expressions for embedded code or 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.
pattern
patternProperties
https://json-schema.org
RFC8259: The JavaScript Object Notation (JSON) Data Interchange Format
RFC3986: Uniform Resource Identifier (URI): Generic Syntax
Test::JSON::Schema::Acceptance: contains the official JSON Schema test suite
JSON::Schema::Tiny: a more minimal implementation of the specification, with fewer dependencies
https://json-schema.org/draft/2019-09/release-notes.html
Understanding JSON Schema: tutorial-focused documentation
Bugs may be submitted through https://github.com/karenetheridge/JSON-Schema-Draft201909/issues.
I am also usually active on irc, as 'ether' at irc.perl.org and irc.freenode.org.
irc.perl.org
irc.freenode.org
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.
To install JSON::Schema::Draft201909, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSON::Schema::Draft201909
CPAN shell
perl -MCPAN -e shell install JSON::Schema::Draft201909
For more information on module installation, please visit the detailed CPAN module installation guide.