Test::...ptance(3pm)

📦

version 1.037 · 6 versions

1.037 · ubuntu resolute, ubuntu stonking (latest)
1.37.0 · opensuse-leap 16.0
1.015 · ubuntu jammy
1.021 · ubuntu noble
1.019 · debian bookworm
1.029 · debian trixie, ubuntu questing

💖 Test::JSON::Schema::Acceptance 💖

ok so this is the 3pm manual page for Test::JSON::Schema::Acceptance, and bestie, if you're writing a JSON Schema validator in perl, this is your moment. 🌟

🌸 NAME 🌸

Test::JSON::Schema::Acceptance — acceptance testing for JSON-Schema based validators. that's the whole job. iconic. 💅

🎀 VERSION 🎀

version 1.037 — yes, she's got a version number, she's official. ✨

✨ SYNOPSIS ✨

so here's the tea: this module lets the tests from the JSON Schema Test Suite (https://github.com/json-schema/JSON-Schema-Test-Suite) be used from perl, so you can test a module that implements the JSON Schema specification (aka "json-schema"). these are literally the same tests that a ton of modules (libraries, plugins, packages, whatever) use to confirm they support json-schema. and like — if you use this module to confirm your support, you get assurance that you're interoperable with all the other modules running these same tests in other languages. cross-language bestie solidarity fr fr. 🫶

over in the JSON::Schema::Modern module, a test could look like this:

use Test2::V0;
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();

and that would determine whether JSON::Schema::Modern's validate method returns the right result for all the cases in the JSON Schema Test Suite — except for the ones listed in skip_tests. slay. 🔥

💜 DESCRIPTION 💜

JSON Schema (http://json-schema.org) is an IETF draft (at time of writing, bestie, drafts move) which lets you define the structure of JSON. so like, you're describing your data's whole personality. 🦋

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.

so this module lets other perl modules (for example JSON::Schema::Modern) test that they're JSON Schema-compliant, by running the tests from the official test suite — no manually converting them into perl tests, no suffering, no tears. 😌

ngl, you're unlikely to want this module unless you're actively trying to write a module that implements the JSON Schema specification and you want to test your compliance. it's giving "niche but essential". 🎯

🛠️ CONSTRUCTOR 🛠️

Test::JSON::Schema::Acceptance->new(specification => $specification_version)

creates a new instance of Test::JSON::Schema::Acceptance. main character entrance, honestly. 👑

available options (which are also available as accessor methods on the object) are:

📋 `specification`

this determines the draft version of the schema you're confirming compliance to. possible values are:

draft3
draft4
draft6
draft7
draft2019-09
draft2020-12
latest (alias for draft2020-12)
v1

the default is latest, but in the synopsis example, JSON::Schema::Modern is testing draft 7 compliance. pick your era bestie. 🕰️

(for backwards compatibility, new can be called with a single numeric argument of 3 to 7, which maps to draft3 through draft7.)

📋 `supported_specifications`

the version(s) that the implementation supports; used to skip adding remote resources that reference unsupported schema versions (for cross-schema tests). defaults to [ $self->specification ].

📋 `test_dir`

instead of specifying a draft specification to test against — which would pick the most appropriate tests for you — 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. DIY era. ✂️

📋 `additional_resources`

a directory of additional resources which should be made available to the implementation under the base URI http://localhost:1234. this dataset is automatically provided if you didn't 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"}). and if you supply an add_resource value to acceptance (see below), this will be done for you. we love a module that does the thing for you. 🫶

📋 `verbose`

optional. when true, prints version information and the test result table such that it's visible during make test or prove. so you can actually see it. ground-breaking. 👀

📋 `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. no point skipping what's already skipped, bestie. 💀

📋 `results`

after calling acceptance, a list of test results are provided here. it's 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 gets printed at the end of the test run. receipts. 🧾

📋 `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're using your own test files. your call, bestie. 🙈

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 can return either one value or two:

a boolean value indicating whether the schema was valid for the input or not (required)
a value containing the result of the evaluation (which will be JSONified in the test output) (optional)

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 can return either one value or two:

a boolean value indicating whether the schema was valid for the input or not (required)
a value containing the result of the evaluation (which will be JSONified in the test output) (optional)

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 the arguments:

a URI (string): the canonical uri to use for the new resource
a data structure containing schema data to be associated with that URI, for use in some tests that use additional resources (see above).
a list of key-value pairs (optional), containing additional options to be passed to the subroutine: keys currently limited to specification_version.

if you don't 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. no takebacks. 😭

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' ],
}

so many flavors, all of them valid. 🌈

`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
]

`json_prettyprint`

JSON-encodes a data structure in a format suitable for human view, used for printing test diagnostics. pretty-printing is self-care. 🌸

`json_encoder`

provides access to the object that provides the json_prettyprint method.

💌 GIVING THANKS 💌

if you found this module to be useful, please show your appreciation by adding a +1 in MetaCPAN (https://metacpan.org/dist/Test-JSON-Schema-Acceptance) and a star in GitHub (https://github.com/karenetheridge/Test-JSON-Schema-Acceptance). it costs nothing and it means everything, bestie. ⭐

🆘 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. come hang out. 💬

👑 AUTHOR 👑

Ben Hutton (@relequestual) <relequest@cpan.org>

🫶 CONTRIBUTORS 🫶

Karen Etheridge <ether@cpan.org>
Daniel Perrett <dp13@sanger.ac.uk>

...and that's part 1, bestie — hold tight, more follows! 🌟

✨ COPYRIGHT AND LICENCE ✨

okay bestie, legal bit, but make it cute 💖

This is free software, licensed under:

The MIT (X11) License

slay, that's the good one ✨

a lil note about the test data 🎀

This distribution includes data from the <https://json-schema.org> test suite, and ngl that data rolls with its own licence — peep share/LICENSE for the deets. different licence, same vibe, don't mix them up 💅

🚨 READ THIS ONE, FR FR 🚨 Permission is explicitly NOT granted to repackage or redistribute this distribution with any files altered or added (like, say, a whole different set of test data) than what was originally published to the Perl Programming Authors Upload Server (PAUSE). and why? because the dependencies of this distribution have very specific expectations about what's in this test data depending on the version. it's giving "the deps are watching" 😭 so don't swap the files out, okay? If you wanna use a different dataset at runtime though? totally allowed, bestie — just go through the test_dir configuration option. that's the move 💖

and that's the whole page, you made it to the end 🫶 this lil beaut came to you via perl v5.40.1, dated 2026-01-23, and it lives its life as Test::...ptance(3pm). go forth and run those tests, you absolute icon 👑✨

📦 where this page comes from

ubuntu resolute: libtest-json-schema-acceptance-perl 1.037-1 · MIT
ubuntu stonking: libtest-json-schema-acceptance-perl 1.037-1 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Test::...ptance(3pm)

💖 Test::JSON::Schema::Acceptance 💖

🌸 NAME 🌸

🎀 VERSION 🎀

✨ SYNOPSIS ✨

💜 DESCRIPTION 💜

🛠️ CONSTRUCTOR 🛠️

📋 specification

📋 supported_specifications

📋 test_dir

📋 additional_resources

📋 verbose

📋 include_optional

📋 skip_dir

📋 results

📋 results_text

📋 test_schemas