The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


JSONSchema::Validator - Validator for JSON Schema Draft4/Draft6/Draft7 and OpenAPI Specification 3.0


version 0.011


    # to get OpenAPI validator in YAML format
    $validator = JSONSchema::Validator->new(resource => 'file:///some/path/to/oas30.yml');
    my ($result, $errors, $warnings) = $validator->validate_request(
        method => 'GET',
        openapi_path => '/user/{id}/profile',
        parameters => {
            path => {
                id => 1234
            query => {
                details => 'short'
            header => {
                header => 'header value'
            cookie => {
                name => 'value'
            body => [$is_exists, $content_type, $data]
    my ($result, $errors, $warnings) = $validator->validate_response(
        method => 'GET',
        openapi_path => '/user/{id}/profile',
        status => '200',
        parameters => {
            header => {
                header => 'header value'
            body => [$is_exists, $content_type, $data]

    # to get JSON Schema Draft4/Draft6/Draft7 validator in JSON format
    $validator = JSONSchema::Validator->new(resource => '')
    my ($result, $errors) = $validator->validate_schema($object_to_validate)


OpenAPI specification and JSON Schema Draft4/Draft6/Draft7 validators with minimum dependencies.



Creates one of the following validators: JSONSchema::Validator::Draft4, JSONSchema::Validator::Draft6, JSONSchema::Validator::Draft7, JSONSchema::Validator::OAS30.

    my $validator = JSONSchema::Validator->new(resource => 'file:///some/path/to/oas30.yml');
    my $validator = JSONSchema::Validator->new(resource => '');
    my $validator = JSONSchema::Validator->new(schema => {'$schema' => 'path/to/schema', ...});
    my $validator = JSONSchema::Validator->new(schema => {...}, specification => 'Draft4');

if parameter specification is not specified then type of validator will be determined by $schema key for JSON Schema Draft4/Draft6/Draft7 and by openapi key for OpenAPI Specification 3.0 in schema parameter.



To get schema by uri


To get explicitly specified schema


To specify specification of schema


Do not validate specified schema


To specify base uri of schema. This parameter used to build absolute path by relative reference in schema. By default base_uri is equal to the resource path if the resource parameter is specified otherwise the $id key in the schema.

Additional parameters need to be looked at in a specific validator class. Currently there are validators: JSONSchema::Validator::Draft4, JSONSchema::Validator::Draft6, JSONSchema::Validator::Draft7, JSONSchema::Validator::OAS30.


Validates all files specified by path globs.

    my $result = JSONSchema::Validator->validate_paths(['/some/path/to/openapi.*.yaml', '/some/path/to/jsonschema.*.json']);
    for my $file (keys %$result) {
        my ($res, $errors) = @{$result->{$file}};




YAML & booleans

When reading schema definitions from YAML, please note that the standard behaviour of YAML::PP and YAML::XS is to read values which evaluate to true or false in a perl context. These values have no recognizable 'boolean type'. This is insufficient for JSON schema validation.

To make the YAML readers and booleans work with JSONSchema::Validator, you need to use the JSON::PP (included in Perl's standard library) module as follows:

  # for YAML::PP
  use YAML::PP;

  my $reader = YAML::PP->new( boolean => 'JSON::PP' );
  # from here, you can freely use the reader to
  # read & write booleans as 'true' and 'false'

  # for YAML::XS
  use YAML::XS;

  my $reader = YAML::XS->new;

  # and whenever you read YAML with this reader, do:
  my $yaml = do {
    local $YAML::XS::Boolean = 'JSON::PP';
    $reader->Load($string); # or $reader->LoadFile('filename');

This isn't a problem when you use the resource argument to the JSONSchema::Validator::new constructor, but if you read your own schema and use the schema argument, this is something to be aware of.

allow_bignum => 1

The allow_bignum = 1> setting (available on JSON::XS and Cpanel::JSON::XS) on deserializers is not supported.

When deserializing a request body with a JSON parser configured with allow_bignum = 1>, floats - even ones which fit into the regular float ranges - will be deserialized as Math::BigFloat. Similarly, integers outside of the internal integer range are deserialized as Math::BigInt. Numbers represented as Math::Big* objects are not recognized as actual numbers and will fail validation.


  • Alexey Stavrov <>

  • Ivan Putintsev <>

  • Anton Fedotov <>

  • Denis Ibaev <>

  • Andrey Khozov <>


  • Erik Huelsmann <>

  • James Waters <>


This software is Copyright (c) 2021 by Alexey Stavrov.

This is free software, licensed under:

  The MIT (X11) License