.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Test::JSON::Schema::Acceptance 3pm" .TH Test::JSON::Schema::Acceptance 3pm "2020-12-07" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Test::JSON::Schema::Acceptance \- Acceptance testing for JSON\-Schema based validators like JSON::Schema .SH "VERSION" .IX Header "VERSION" version 1.003 .SH "SYNOPSIS" .IX Header "SYNOPSIS" This module allows the \&\s-1JSON\s0 Schema Test Suite tests to be used in perl to test a module that implements the \s-1JSON\s0 Schema specification (\*(L"json-schema\*(R"). 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. .PP In the JSON::Schema module, a test could look like the following: .PP .Vb 3 \& use Test::More; \& use JSON::Schema; \& use Test::JSON::Schema::Acceptance; \& \& my $accepter = Test::JSON::Schema::Acceptance\->new(specification => \*(Aqdraft3\*(Aq); \& \& $accepter\->acceptance( \& validate_data => sub { \& my ($schema, $input_data) = @_; \& return JSON::Schema\->new($schema)\->validate($input_data); \& }, \& todo_tests => [ { file => \*(Aqdependencies.json\*(Aq } ], \& ); \& \& done_testing(); .Ve .PP This would determine if JSON::Schema's \f(CW\*(C`validate\*(C'\fR method returns the right result for all of the cases in the \s-1JSON\s0 Schema Test Suite, except for those listed in \f(CW$skip_tests\fR. .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\s-1JSON\s0 Schema is an \s-1IETF\s0 draft (at time of writing) which allows you to define the structure of \s-1JSON.\s0 .PP From the overview of the draft 2019\-09 version of the specification : .Sp .RS 4 This document proposes a new media type \*(L"application/schema+json\*(R" to identify a \s-1JSON\s0 Schema for describing \s-1JSON\s0 data. It also proposes a further optional media type, \&\*(L"application/schema\-instance+json\*(R", to provide additional integration features. \s-1JSON\s0 Schemas are themselves \s-1JSON\s0 documents. This, and related specifications, define keywords allowing authors to describe \s-1JSON\s0 data in several ways. .Sp \&\s-1JSON\s0 Schema uses keywords to assert constraints on \s-1JSON\s0 instances or annotate those instances with additional information. Additional keywords are used to apply assertions and annotations to more complex \s-1JSON\s0 data structures, or based on some sort of condition. .RE .PP This module allows other perl modules (for example JSON::Schema) to test that they are \s-1JSON\s0 Schema-compliant, by running the tests from the official test suite, without having to manually convert them to perl tests. .PP You are unlikely to want this module, unless you are attempting to write a module which implements \&\s-1JSON\s0 Schema the specification, and want to test your compliance. .SH "CONSTRUCTOR" .IX Header "CONSTRUCTOR" .Vb 1 \& Test::JSON::Schema::Acceptance\->new(specification => $specification_version) .Ve .PP Create a new instance of Test::JSON::Schema::Acceptance. .PP Available options (which are also available as accessor methods on the object) are: .SS "specification" .IX Subsection "specification" This determines the draft version of the schema to confirm compliance to. Possible values are: .IP "\(bu" 4 \&\f(CW\*(C`draft3\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`draft4\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`draft6\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`draft7\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`draft2019\-09\*(C'\fR .IP "\(bu" 4 \&\f(CW\*(C`latest\*(C'\fR (alias for \f(CW\*(C`draft2019\-09\*(C'\fR) .PP The default is \f(CW\*(C`latest\*(C'\fR, but in the synopsis example, JSON::Schema is testing draft 3 compliance. .PP (For backwards compatibility, \f(CW\*(C`new\*(C'\fR can be called with a single numeric argument of 3 to 7, which maps to \f(CW\*(C`draft3\*(C'\fR through \f(CW\*(C`draft7\*(C'\fR.) .SS "test_dir" .IX Subsection "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 \fI.json\fR files following the format described in . .SS "additional_resources" .IX Subsection "additional_resources" A directory of additional resources which should be made available to the implementation under the base \s-1URI\s0 \f(CW\*(C`http://localhost:1234\*(C'\fR. This is automatically provided if you did not override \&\f(CW\*(C`/test_dir\*(C'\fR; otherwise, you need to supply it yourself, if any tests require it (for example by containing \f(CW\*(C`{"$ref": "http://localhost:1234/foo.json/#a/b/c"}\*(C'\fR). If you supply an \&\*(L"add_resource\*(R" value to \*(L"acceptance\*(R" (see below), this will be done for you. .SS "verbose" .IX Subsection "verbose" Optional. When true, prints version information and test result table such that it is visible during \f(CW\*(C`make test\*(C'\fR or \f(CW\*(C`prove\*(C'\fR. .SS "include_optional" .IX Subsection "include_optional" Optional. When true, tests in subdirectories (most notably \fIoptional/\fR are also included. .SH "SUBROUTINES/METHODS" .IX Header "SUBROUTINES/METHODS" .SS "acceptance" .IX Subsection "acceptance" Accepts a hash of options as its arguments. .PP (Backwards-compatibility mode: accepts a subroutine which is used as \f(CW\*(C`validate_json_string\*(C'\fR, and a hashref of arguments.) .PP Available options are: .PP \fIvalidate_data\fR .IX Subsection "validate_data" .PP A subroutine reference, which is passed two arguments: the \s-1JSON\s0 Schema, and the \fBinflated\fR data structure to be validated. .PP The subroutine should return truthy or falsey depending on if the schema was valid for the input or not. .PP Either \f(CW\*(C`validate_data\*(C'\fR or \f(CW\*(C`validate_json_string\*(C'\fR is required. .PP \fIvalidate_json_string\fR .IX Subsection "validate_json_string" .PP A subroutine reference, which is passed two arguments: the \s-1JSON\s0 Schema, and the \fB\s-1JSON\s0 string\fR containing the data to be validated. .PP The subroutine should return truthy or falsey depending on if the schema was valid for the input or not. .PP Either \f(CW\*(C`validate_data\*(C'\fR or \f(CW\*(C`validate_json_string\*(C'\fR is required. .PP \fIadd_resource\fR .IX Subsection "add_resource" .PP Optional. A subroutine reference, which will be called at the start of \*(L"acceptance\*(R" multiple times, with two arguments: a \s-1URI\s0 (string), and a data structure containing schema data to be associated with that \s-1URI,\s0 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. .PP For more information, see . .PP \fItests\fR .IX Subsection "tests" .PP Optional. Restricts tests to just those mentioned (the conditions are ANDed together, not ORed). The syntax can take one of many forms: .PP .Vb 2 \& # run tests in this file \& tests => { file => \*(Aqdependencies.json\*(Aq } \& \& # run tests in these files \& tests => { file => [ \*(Aqdependencies.json\*(Aq, \*(AqrefRemote.json\*(Aq ] } \& \& # run tests in this file with this group description \& tests => { \& file => \*(AqrefRemote.json\*(Aq, \& group_description => \*(Aqremote ref\*(Aq, \& } \& \& # run tests in this file with these group descriptions \& tests => { \& file => \*(Aqconst.json\*(Aq, \& group_description => [ \*(Aqconst validation\*(Aq, \*(Aqconst with object\*(Aq ], \& } \& \& # run tests in this file with this group description and test description \& tests => { \& file => \*(Aqconst.json\*(Aq, \& group_description => \*(Aqconst validation\*(Aq, \& test_description => \*(Aqanother type is invalid\*(Aq, \& } \& \& # run tests in this file with this group description and these test descriptions \& tests => { \& file => \*(Aqconst.json\*(Aq, \& group_description => \*(Aqconst validation\*(Aq, \& test_description => [ \*(Aqsame value is valid\*(Aq, \*(Aqanother type is invalid\*(Aq ], \& } .Ve .PP \fItodo_tests\fR .IX Subsection "todo_tests" .PP Optional. Mentioned tests will run as \*(L"\s-1TODO\*(R"\s0. Uses arrayrefs of the same hashref structure as \*(L"tests\*(R" above, which are ORed together. .PP .Vb 7 \& todo_tests => [ \& # all tests in this file are TODO \& { file => \*(Aqdependencies.json\*(Aq }, \& # just some tests in this file are TODO \& { file => \*(Aqboolean_schema.json\*(Aq, test_description => \*(Aqarray is invalid\*(Aq }, \& # .. etc \& ] .Ve .SS "results" .IX Subsection "results" After calling \*(L"acceptance\*(R", a list of test results are provided here. It is an arrayref of hashrefs with four keys: .IP "\(bu" 4 file \- the filename .IP "\(bu" 4 pass \- the number of pass results for that file .IP "\(bu" 4 todo_fail \- the number of fail results for that file that were marked \s-1TODO\s0 .IP "\(bu" 4 fail \- the number of fail results for that file (not including \s-1TODO\s0 tests) .SH "ACKNOWLEDGEMENTS" .IX Header "ACKNOWLEDGEMENTS" Daniel Perrett for the concept and help in design. .PP Ricardo Signes for direction to and creation of Test::Fatal. .PP Various others in #perl\-help. .SH "SUPPORT" .IX Header "SUPPORT" Bugs may be submitted through . .SH "AUTHOR" .IX Header "AUTHOR" Ben Hutton (@relequestual) .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" .IP "\(bu" 4 Karen Etheridge .IP "\(bu" 4 Daniel Perrett .SH "COPYRIGHT AND LICENCE" .IX Header "COPYRIGHT AND LICENCE" This software is Copyright (c) 2015 by Ben Hutton. .PP This is free software, licensed under: .PP .Vb 1 \& The MIT (X11) License .Ve