The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Data-JSONSchema-Ajv-0.03
River stage zero No dependents
1 ++
/ Data::JSONSchema::Ajv

NAME

Data::JSONSchema::Ajv - JSON Schema Validator wrapping Ajv

VERSION

version 0.03

DESCRIPTION

JSON Schema Validator wrapping Ajv

SYNOPSIS

    use Test::More;
    use Data::JSONSchema::Ajv;

    my $ajv_options = {};
    my $my_options  = {};

    my $ajv     = Data::JSONSchema::Ajv->new($ajv_options, $my_options);

    my $validator = $ajv->make_validator(
        {    # http://json-schema.org/examples.html
            title      => "Example Schema",
            type       => "object",
            properties => {
                firstName => { type => "string" },
                lastName  => { type => "string" },
                age       => {
                    description => "Age in years",
                    type        => "integer",
                    minimum     => 0
                }
            },
            required => [ "firstName", "lastName" ],
        }
    );

    my $payload = { firstName => 'Valentina', familyName => 'Tereshkova' };

    my $result = $validator->validate($payload);

    if ($result) {
        is_deeply(
            $result,
            [   {   dataPath   => "",
                    keyword    => "required",
                    message    => "should have required property 'lastName'",
                    params     => { missingProperty => "lastName" },
                    schemaPath => "#/required"
                }
            ],
            "Expected errors thrown"
        );
    } else {
        fail(
            "validate() returned a false value, which means the example " .
            "unexpectedly validated"
        );
    }

WHAT WHY

This module is an offensively light-weight wrapper Ajv.

Light-weight in this context just means it's only 50 lines or so of actual Perl.

METHODS

new

  my $ajv = Data::JSONSchema::Ajv->new(
      { v5 => $JSON::PP::true }, # Ajv options. Try: {},
      {}, # Module options. None at this time
  );

Instantiates a new JavaScript::Duktape::XS environment and loads Ajv into it. Accepts two hashrefs (or undefs). The first is passed straight through to Ajv, whose options are documented here.

There are no options at this time to pass this module itself.

You *must* read the section on SCHEMA VERSIONING below.

make_validator

  my $validator = $ajv->make_validator( $hashref_schema );

Compiles your schema using Ajv and return a Data::JSONSchema::Ajv::Validator object, documented immediately below.

duktape

Need to do something else, and something magic? This is a read-only accessor to the Duktape env.

Data::JSONSchema::Ajv::Validator

Single method object:

validate

  my $errors = $validator->validate( $data_structure );

Validate a data-structure against the schema. Returns undef on success, and a data-structure complaining on failure. The data-structure is whatever Ajv produces - you can either read its documentation, or be lazy and simply Data::Dumper it.

BOOLEANS AND UNDEFINED/NULL

Perl has no special Boolean types. JSON (and indeed JavaScript) does. On load, this module does a bit of magic in the very simple Data::JSONSchema::Ajv::Types module, which recognizes and converts common Perl-defined standins for this in to JavaScript::Duktape::XS::Bool.

Currently that's a small list consisting of the boolean objects from Types::Serialiser::BooleanBase, JSON::Boolean, and JSON::PP::Boolean but you can easily overwrite the $visitor object and send me a patch for your favourite type.

Calls to make_validator and validate will run their input through the visitor object, and convert their Booleans. This means you can push data in that you've read with, say, JSON::XS without having to think about it.

Also: undef --> will be converted to JS null values -- undefined isn't value in JSON.

SCHEMA VERSIONING

The Ajv docs have the somewhat confusing messages about schema versions, and when trying to support the most recent Ajv, I got confusing message about Duktape. As a result, we're using Ajv 4.11.8 which supports draft-04 style schemas only. This will probably change in the future, but life's too short right now and I need something that works. Patches encouraged.

SEE ALSO

This module was written because I couldn't get any of the other JSON Schema validators to work.

Toby Inkster wrote JSON::Schema, which I had high hopes for, because he's a smart cookie, but it seems like it's very out of date compared to modern schemas.

I was unable to get JSON::Validator to fail validation for any schema I gave it. That's probably due to having miswritten my schemas, but it didn't give me any hints, and I did get some errors along the lines of Can't locate method validate_HASH(blahblah) and so I gave up. I also find it mildly offensive that (the most excellent) Mojolicious is a dependency for a JSON tool. Additionally it doesn't validate the schemas themselves, and I'm too stupid to use a tool like that.

Test::JSON::Schema::Acceptance provides some schema tests. This passes all of thems except the ones that require going and downloading external schemas.

AUTHOR

All the hard work was done by the guy who wrote Ajv, Evgeny Poberezkin.

This Perl wrapper written by Peter Sergeant.