JSON::Validator - Validate data against a JSON schema
0.55
use JSON::Validator; my $validator = JSON::Validator->new; # Define a schema - http://json-schema.org/examples.html # You can also load schema from disk or web $validator->schema( { type => "object", required => ["firstName", "lastName"], properties => { firstName => {type => "string"}, lastName => {type => "string"}, age => {type => "integer", minimum => 0, description => "Age in years"} } } ); # Validate your data @errors = $validator->validate({firstName => "Jan Henning", lastName => "Thorsen", age => -42}); # Do something if any errors was found die "@errors" if @errors;
JSON::Validator is a class for validating data against JSON schemas. You might want to use this instead of JSON::Schema if you need to validate data against draft 4 of the specification.
This module is currently EXPERIMENTAL. Hopefully nothing drastic will change, but it needs to fit together nicely with Swagger2 - Since this is a spin-off project.
JSON::Validator can load JSON schemas in multiple formats: Plain perl data structured (as shown in "SYNOPSIS") or files on disk/web in the JSON/YAML format. The JSON parsing is done using Mojo::JSON, while the YAML parsing is done with an optional modules which need to be installed manually. JSON::Validator will look for the YAML modules in this order: YAML::XS, YAML::Syck, YAML::Tiny, YAML. The order is set by which module that performs the best, so it might change in the future.
Here are some resources that are related to JSON schemas and validation:
http://json-schema.org/documentation.html
http://spacetelescope.github.io/understanding-json-schema/index.html
http://jsonary.com/documentation/json-schema/
https://github.com/json-schema/json-schema/
Swagger2
The method "validate" and the function "validate_json" returns error objects when the input data violates the "schema". Each of the objects looks like this:
bless { message => "Some description", path => "/json/path/to/node", }, "JSON::Validator::Error"
The error object overloads the following operators:
bool
Returns a true value.
string
Returns the "path" and "message" part as a string: "$path: $message".
Have a look at the test suite for documented examples of the error cases. Especially look at jv-allof.t, jv-anyof.t and jv-oneof.t.
jv-allof.t
jv-anyof.t
jv-oneof.t
The special cases for "allOf", "anyOf" and "oneOf" will contain the error messages from all the failing rules below. It can be a bit hard to read, so if the error message is long, then you might want to run a smaller test with JSON_VALIDATOR_DEBUG=1.
JSON_VALIDATOR_DEBUG=1
Example error object:
bless { message => "[0] String is too long: 8/5. [1] Expected number - got string.", path => "/json/path/to/node", }, "JSON::Validator::Error"
Note that these error messages are subject for change. Any suggestions are most welcome!
use JSON::Validator "validate_json"; @errors = validate_json $data, $schema;
This can be useful in web applications:
@errors = validate_json $c->req->json, "data://main/spec.json";
See also "validate" and "ERROR OBJECT" for more details.
$self = $self->cache_dir($path); $path = $self->cache_dir;
Path to where downloaded spec files should be cached. Defaults to JSON_VALIDATOR_CACHE_DIR or the bundled spec files that are shipped with this distribution.
JSON_VALIDATOR_CACHE_DIR
$self = $self->coerce(1); $bool = $self->coerce;
Set this to true if you want to coerce numbers into string and the other way around.
This is EXPERIMENTAL and could be removed without notice!
$hash_ref = $self->formats; $self = $self->formats(\%hash);
Holds a hash-ref, where the keys are supported JSON type "formats", and the values holds a code block which can validate a given format.
Note! The modules mentioned below are optional.
date-time
An RFC3339 timestamp in UTC time. This is formatted as "YYYY-MM-DDThh:mm:ss.fffZ". The milliseconds portion (".fff") is optional
email
Validated against the RFC5322 spec.
hostname
Will be validated using Data::Validate::Domain if installed.
ipv4
Will be validated using Data::Validate::IP if installed or fall back to a plain IPv4 IP regex.
ipv6
Will be validated using Data::Validate::IP if installed.
uri
Validated against the RFC3986 spec.
$ua = $self->ua; $self = $self->ua(Mojo::UserAgent->new);
Holds a Mojo::UserAgent object, used by "schema" to load a JSON schema from remote location.
Note that the default Mojo::UserAgent will detect proxy settings and have "max_redirects" in Mojo::UserAgent set to 3. (These settings are EXPERIMENTAL and might change without a warning)
$self = $self->schema(\%schema); $self = $self->schema($url); $schema = $self->schema;
Used to set a schema from either a data structure or a URL.
$schema will be a Mojo::JSON::Pointer object when loaded, and undef by default.
$schema
undef
The $url can take many forms, but needs to point to a text file in the JSON or YAML format.
$url
http://... or https://...
A web resource will be fetched using the Mojo::UserAgent, stored in "ua".
data://Some::Module/file.name
This version will use "data_section" in Mojo::Loader to load "file.name" from the module "Some::Module".
/path/to/file
An URL (without a recognized scheme) will be loaded from disk.
$self = $class->singleton;
Returns the JSON::Validator object used by "validate_json".
@errors = $self->validate($data);
Validates $data against a given JSON "schema". @errors will contain validation error objects or be an empty list on success.
$data
@errors
See "ERROR OBJECT" for details.
Copyright (C) 2014-2015, Jan Henning Thorsen
This program is free software, you can redistribute it and/or modify it under the terms of the Artistic License version 2.0.
Jan Henning Thorsen - jhthorsen@cpan.org
jhthorsen@cpan.org
To install JSON::Validator, copy and paste the appropriate command in to your terminal.
cpanm
cpanm JSON::Validator
CPAN shell
perl -MCPAN -e shell install JSON::Validator
For more information on module installation, please visit the detailed CPAN module installation guide.