/ 
JSON-Schema-Draft201909-0.009
River stage zero No dependents
/ JSON::Schema::Draft201909

NAME

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

VERSION

version 0.009

SYNOPSIS

use JSON::Schema::Draft201909;

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

DESCRIPTION

This module aims to be a fully-compliant JSON Schema evaluator and validator, targeting the currently-latest Draft 2019-09 version of the specification.

CONFIGURATION OPTIONS

output_format

One of: flag, basic, detailed, verbose. Defaults to basic. Passed to "output_format" in JSON::Schema::Draft201909::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 possible errors.

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. Defaults to 50.

validate_formats

When true, the format keyword will be treated as an assertion, not merely an annotation. Defaults to false.

format_validations

An optional hashref that allows overriding the validation method for formats, or adding new ones. Existing formats 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.

METHODS

evaluate_json_string

$result = $js->evaluate_json_string($data_as_json_string, $schema_data);

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.

The result is a JSON::Schema::Draft201909::Result object, which can also be used as a boolean.

evaluate

$result = $js->evaluate($instance_data, $schema_data);

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

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.

The result is a JSON::Schema::Draft201909::Result object, which can also be used as a boolean.

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::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 pre-loaded.

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 this turns out to be an issue in real environments, I may have to implement a lax_scalars option.

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

FORMAT VALIDATION

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 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):

SPECIFICATION COMPLIANCE

Until version 1.000 is released, this implementation is not fully specification-compliant.

To date, missing components (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)

  • multiple output formats (https://json-schema.org/draft/2019-09/json-schema-core.html#rfc.section.10)

  • annotation collection (including the "format", "meta-data" and "content" vocabularies)

  • examination of the $schema keyword for deviation from the standard metaschema, including changes to vocabulary behaviour

SECURITY CONSIDERATIONS

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 RUN SCHEMAS FROM UNTRUSTED SOURCES.

SEE ALSO

SUPPORT

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.

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.