Provided by: libtest-json-schema-acceptance-perl_1.018-1_all 
NAME
Test::JSON::Schema::Acceptance - Acceptance testing for JSON-Schema based validators
VERSION
version 1.018
SYNOPSIS
This module allows the JSON Schema Test Suite <https://github.com/json-schema/JSON-Schema-
Test-Suite> tests to be used in perl to test a module that implements the JSON Schema
specification ("json-schema"). These are the same tests that many modules (libraries,
plugins, packages, etc.) use to confirm support of json-schema. Using this module to
confirm support gives assurance of interoperability with other modules that run the same
tests in different languages.
In the JSON::Schema::Modern module, a test could look like the following:
use Test::More;
use JSON::Schema::Modern;
use Test::JSON::Schema::Acceptance;
my $accepter = Test::JSON::Schema::Acceptance->new(specification => 'draft7');
$accepter->acceptance(
validate_data => sub ($schema, $input_data) {
return JSON::Schema::Modern->new($schema)->validate($input_data);
},
todo_tests => [ { file => 'dependencies.json' } ],
);
done_testing();
This would determine if JSON::Schema::Modern's "validate" method returns the right result
for all of the cases in the JSON Schema Test Suite, except for those listed in
$skip_tests.
DESCRIPTION
JSON Schema <http://json-schema.org> is an IETF draft (at time of writing) which allows
you to define the structure of JSON.
From the overview of the draft 2020-12 version of the specification <https://json-
schema.org/draft/2020-12/json-schema-core.html#rfc.section.3>:
This document proposes a new media type "application/schema+json" to identify a JSON
Schema for describing JSON data. It also proposes a further optional media type,
"application/schema-instance+json", to provide additional integration features. JSON
Schemas are themselves JSON documents. This, and related specifications, define
keywords allowing authors to describe JSON data in several ways.
JSON Schema uses keywords to assert constraints on JSON instances or annotate those
instances with additional information. Additional keywords are used to apply
assertions and annotations to more complex JSON data structures, or based on some sort
of condition.
This module allows other perl modules (for example JSON::Schema::Modern) to test that they
are JSON Schema-compliant, by running the tests from the official test suite, without
having to manually convert them to perl tests.
You are unlikely to want this module, unless you are attempting to write a module which
implements JSON Schema the specification, and want to test your compliance.
CONSTRUCTOR
Test::JSON::Schema::Acceptance->new(specification => $specification_version)
Create a new instance of Test::JSON::Schema::Acceptance.
Available options (which are also available as accessor methods on the object) are:
specification
This determines the draft version of the schema to confirm compliance to. Possible values
are:
• "draft3"
• "draft4"
• "draft6"
• "draft7"
• "draft2019-09"
• "draft2020-12"
• "latest" (alias for "draft2020-12")
• "draft-next"
The default is "latest", but in the synopsis example, JSON::Schema::Modern is testing
draft 7 compliance.
(For backwards compatibility, "new" can be called with a single numeric argument of 3 to
7, which maps to "draft3" through "draft7".)
test_dir
Instead of specifying a draft specification to test against, which will select the most
appropriate tests, you can pass in the name of a directory of tests to run directly. Files
in this directory should be .json files following the format described in
<https://github.com/json-schema-org/JSON-Schema-Test-Suite/blob/main/README.md>.
additional_resources
A directory of additional resources which should be made available to the implementation
under the base URI "http://localhost:1234". This is automatically provided if you did not
override "/test_dir"; otherwise, you need to supply it yourself, if any tests require it
(for example by containing "{"$ref": "http://localhost:1234/foo.json/#a/b/c"}"). If you
supply an "add_resource" value to "acceptance" (see below), this will be done for you.
verbose
Optional. When true, prints version information and the test result table such that it is
visible during "make test" or "prove".
include_optional
Optional. When true, tests in subdirectories (most notably optional/ are also included.
skip_dir
Optional. Pass a string or arrayref consisting of relative path name(s) to indicate
directories (within the test directory as specified above with "specification" or
"test_dir") which will be skipped. Note that this is only useful currently with
"include_optional =" 1>, as otherwise all subdirectories would be skipped anyway.
results
After calling "acceptance", a list of test results are provided here. It is an arrayref of
hashrefs with four keys:
• file - the filename
• pass - the number of pass results for that file
• todo_fail - the number of fail results for that file that were marked TODO
• fail - the number of fail results for that file (not including TODO tests)
results_text
After calling "acceptance", a text string tabulating the test results are provided here.
This is the same table that is printed at the end of the test run.
test_schemas
Optional. A boolean that, when true, will test every schema against its specification
metaschema. (When set, "specification" must also be set.)
This normally should not be set as the official test suite has already been sanity-tested,
but you may want to set this in development environments if you are using your own test
files.
Defaults to false.
SUBROUTINES/METHODS
acceptance
Accepts a hash of options as its arguments.
(Backwards-compatibility mode: accepts a subroutine which is used as
"validate_json_string", and a hashref of arguments.)
Available options are:
validate_data
A subroutine reference, which is passed two arguments: the JSON Schema, and the inflated
data structure to be validated. This is the main entry point to your JSON Schema library
being tested.
The subroutine should return truthy or falsey depending on if the schema was valid for the
input or not.
Either "validate_data" or "validate_json_string" is required.
validate_json_string
A subroutine reference, which is passed two arguments: the JSON Schema, and the JSON
string containing the data to be validated. This is an alternative to "validate_data"
above, if your library only accepts JSON strings.
The subroutine should return truthy or falsey depending on if the schema was valid for the
input or not.
Exactly one of "validate_data" or "validate_json_string" is required.
add_resource
Optional. A subroutine reference, which will be called at the start of "acceptance"
multiple times, with two arguments: a URI (string), and a data structure containing schema
data to be associated with that URI, for use in some tests that use additional resources
(see above). If you do not provide this option, you will be responsible for ensuring that
those additional resources are made available to your implementation for the successful
execution of the tests that rely on them.
For more information, see
<https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.9.1.2>.
tests
Optional. Restricts tests to just those mentioned (the conditions are ANDed together, not
ORed). The syntax can take one of many forms:
# run tests in this file
tests => { file => 'dependencies.json' }
# run tests in these files
tests => { file => [ 'dependencies.json', 'refRemote.json' ] }
# run tests in this file with this group description
tests => {
file => 'refRemote.json',
group_description => 'remote ref',
}
# run tests in this file with these group descriptions
tests => {
file => 'const.json',
group_description => [ 'const validation', 'const with object' ],
}
# run tests in this file with this group description and test description
tests => {
file => 'const.json',
group_description => 'const validation',
test_description => 'another type is invalid',
}
# run tests in this file with this group description and these test descriptions
tests => {
file => 'const.json',
group_description => 'const validation',
test_description => [ 'same value is valid', 'another type is invalid' ],
}
todo_tests
Optional. Mentioned tests will run as "TODO". Uses arrayrefs of the same hashref structure
as "tests" above, which are ORed together.
todo_tests => [
# all tests in this file are TODO
{ file => 'dependencies.json' },
# just some tests in this file are TODO
{ file => 'boolean_schema.json', test_description => 'array is invalid' },
# .. etc
]
ACKNOWLEDGEMENTS
Daniel Perrett <perrettdl@cpan.org> for the concept and help in design.
Ricardo Signes <rjbs@cpan.org> for direction to and creation of Test::Fatal.
Various others in #perl-help.
SUPPORT
Bugs may be submitted through
<https://github.com/karenetheridge/Test-JSON-Schema-Acceptance/issues>.
You can also find me on the JSON Schema Slack server <https://json-schema.slack.com> and
OpenAPI Slack server <https://open-api.slack.com>, which are also great resources for
finding help.
AUTHOR
Ben Hutton (@relequestual) <relequest@cpan.org>
CONTRIBUTORS
• Karen Etheridge <ether@cpan.org>
• Daniel Perrett <dp13@sanger.ac.uk>
COPYRIGHT AND LICENCE
This software is Copyright (c) 2015 by Ben Hutton.
This is free software, licensed under:
The MIT (X11) License
This distribution includes data from the <https://json-schema.org> test suite, which
carries its own licence (see share/LICENSE).