++ed by:

14 PAUSE users
10 non-PAUSE users.

Jan Henning Thorsen


JSON::Validator - Validate data against a JSON schema




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

Supported schema formats

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:



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



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


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

The $url can take many forms, but needs to point to a text file in the JSON or YAML format.

  • 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. It will be empty on success.

Example error object:

  bless {
    message => "Some description",
    path => "/json/path/to/node",
  }, "JSON::Validator::Error"

The error objects are always true in boolean context and will stringify. The stringification format is subject to change.


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