/ 
JSON-Schema-Modern-0.544
River stage one • 4 direct dependents • 6 total dependents
/ JSON::Schema::Modern

NAME

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

VERSION

version 0.544

SYNOPSIS

use JSON::Schema::Modern;

$js = JSON::Schema::Modern->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 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 (draft2020-12). When left unset, the use of $schema keywords in the schema is permitted, to switch between draft versions.

May be one of:

  • draft2020-12, corresponding to metaschema https://json-schema.org/draft/2020-12/schema.

  • draft2019-09, corresponding to metaschema https://json-schema.org/draft/2019-09/schema.

  • draft7, corresponding to metaschema http://json-schema.org/draft-07/schema#

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. Be aware that this can result in invalid results in the presence of keywords that depend on annotations, namely unevaluatedItems and unevaluatedProperties.

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

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.

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, 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). Defaults to false.

annotate_unknown_keywords

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

scalarref_booleans

When true, any type 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.

strict

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

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). 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", "annotate_unknown_keywords", "scalarref_booleans", "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 result 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", "annotate_unknown_keywords", "scalarref_booleans", "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 result is a JSON::Schema::Modern::Result object, which can also be used as a boolean.

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(no_nines => { type => 'number', sub => sub ($value) { $value =~ m/^[0-8]$$/ });

Adds support for a custom format. The data type that this format applies to must be supplied; all values of any other type will automatically be deemed to be valid, and will not be passed to the subref.

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

The class must compose the JSON::Schema::Modern::Vocabulary role and implement the vocabulary and keywords methods.

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

  • application/schema+json

  • application/schema-instance+json

  • application/octet-stream

  • text/plain

get_media_type

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

You can use it thusly:

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_media_type('application/furble' => sub ($content_ref) {
  return \ ...;  # data representing the deserialized content for Content-Type: application/furble
});

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

  • base64

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

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

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:

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.

SEE ALSO

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 and OpenAPI Slack server, 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.