JSONSchema::Validator(3)

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

VERSION
version 0.011

SYNOPSIS
    # 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 => 'http://example.com/draft4/schema.json')
    my ($result, $errors) = $validator->validate_schema($object_to_validate)

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

METHODS

  new
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 => 'http://example.com/draft4/schema.json');
    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.

Parameters:

resources
    To get schema by uri

schema
    To get explicitly specified schema

specification
    To specify specification of schema

validate_schema
    Do not validate specified schema

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

  validate_paths
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}};
    }

  validate_resource

  validate_resource_schema

CAVEATS

  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.

AUTHORS

•   Alexey Stavrov <logioniz@ya.ru>

•   Ivan Putintsev <uid@rydlab.ru>

•   Anton Fedotov <tosha.fedotov.2000@gmail.com>

•   Denis Ibaev <dionys@gmail.com>

•   Andrey Khozov <andrey@rydlab.ru>

CONTRIBUTORS

•   Erik Huelsmann <ehuels@gmail.com>

•   James Waters <james@jcwaters.co.uk>

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

This is free software, licensed under:

  The MIT (X11) License