JSON::Validator(3pm)

1JSON::Validator(3)    User Contributed Perl Documentation   JSON::Validator(3)
2
3
4

NAME

6       JSON::Validator - Validate data against a JSON schema
7

SYNOPSIS

9   Using a schema object
10       JSON::Validator::Schema or any of the sub classes can be used instead
11       of JSON::Validator. The only reason to use JSON::Validator directly is
12       if you don't know the schema version up front.
13
14   Basics
15         use JSON::Validator;
16         my $jv = JSON::Validator->new;
17
18         # Define a schema - http://json-schema.org/learn/miscellaneous-examples.html
19         # You can also load schema from disk or web
20         $jv->schema({
21           type       => "object",
22           required   => ["firstName", "lastName"],
23           properties => {
24             firstName => {type => "string"},
25             lastName  => {type => "string"},
26             age       => {type => "integer", minimum => 0, description => "Age in years"}
27           }
28         });
29
30         # Validate your data
31         my @errors = $jv->validate({firstName => "Jan Henning", lastName => "Thorsen", age => -42});
32
33         # Do something if any errors was found
34         die "@errors" if @errors;
35
36   Using joi
37         # Use joi() to build the schema
38         use JSON::Validator::Joi 'joi';
39
40         $jv->schema(joi->object->props({
41           firstName => joi->string->required,
42           lastName  => joi->string->required,
43           age       => joi->integer->min(0),
44         }));
45
46         # joi() can also validate directly
47         my @errors = joi(
48           {firstName => "Jan Henning", lastName => "Thorsen", age => -42},
49           joi->object->props({
50             firstName => joi->string->required,
51             lastName  => joi->string->required,
52             age       => joi->integer->min(0),
53           }),
54         );
55

DESCRIPTION

57       JSON::Validator is a data structure validation library based around
58       JSON Schema <https://json-schema.org/>. This module can be used
59       directly with a JSON schema or you can use the elegant DSL schema-
60       builder JSON::Validator::Joi to define the schema programmatically.
61
62   Supported schema formats
63       JSON::Validator can load JSON schemas in multiple formats: Plain perl
64       data structured (as shown in "SYNOPSIS"), JSON or YAML. The JSON
65       parsing is done with Mojo::JSON, while YAML files requires YAML::PP or
66       YAML::XS.
67
68   Resources
69       Here are some resources that are related to JSON schemas and
70       validation:
71
72       •   <http://json-schema.org/documentation.html>
73
74       •   <https://json-schema.org/understanding-json-schema/index.html>
75
76       •   <https://github.com/json-schema/json-schema/>
77
78   Bundled specifications
79       This module comes with some JSON specifications bundled, so your
80       application don't have to fetch those from the web. These
81       specifications should be up to date, but please submit an issue if they
82       are not.
83
84       Files referenced to an URL will automatically be cached if the first
85       element in "cache_paths" is a writable directory. Note that the cache
86       headers for the remote assets are not honored, so you will manually
87       need to remove any cached file, should you need to refresh them.
88
89       To download and cache an online asset, do this:
90
91         JSON_VALIDATOR_CACHE_PATH=/some/writable/directory perl myapp.pl
92
93       Here is the list of the bundled specifications:
94
95       • JSON schema, draft 4, 6, 7, 2019-09.
96
97         Web page: <http://json-schema.org>
98
99         $ref: <http://json-schema.org/draft-04/schema#>,
100         <http://json-schema.org/draft-06/schema#>,
101         <http://json-schema.org/draft-07/schema#>.
102
103       • JSON schema for JSONPatch files
104
105         Web page: <http://jsonpatch.com>
106
107         $ref: <http://json.schemastore.org/json-patch#>
108
109       • Swagger / OpenAPI specification, version 2
110
111         Web page: <https://openapis.org>
112
113         $ref: <http://swagger.io/v2/schema.json#>
114
115       • OpenAPI specification, version 3
116
117         Web page: <https://openapis.org>
118
119         $ref: https://spec.openapis.org/oas/3.0/schema/2019-04-02
120         <https://github.com/OAI/OpenAPI-
121         Specification/blob/master/schemas/v3.0/schema.json>
122
123         This specification is still EXPERIMENTAL.
124
125       • Swagger Petstore
126
127         This is used for unit tests, and should not be relied on by external
128         users.
129
130   Optional modules
131       • Sereal::Encoder
132
133         Installing Sereal::Encoder v4.00 (or later) will make "data_checksum"
134         in JSON::Validator::Util significantly faster. This function is used
135         both when parsing schemas and validating data.
136
137       • Format validators
138
139         See the documentation in JSON::Validator::Formats for other optional
140         modules to do validation of specific "format", such as "hostname",
141         "ipv4" and others.
142

ATTRIBUTES

144   cache_paths
145       Proxy attribute for "cache_paths" in JSON::Validator::Store.
146
147   formats
148       This attribute will be used as default value for "formats" in
149       JSON::Validator::Schema. It is highly recommended to change this
150       directly on the "schema" instead:
151
152         $jv->formats(...);         # Legacy
153         $jv->schema->formats(...); # Recommended way
154
155   recursive_data_protection
156       This attribute will be used as default value for
157       "recursive_data_protection" in JSON::Validator::Schema. It is highly
158       recommended to change this directly on the "schema" instead:
159
160         $jv->recursive_data_protection(...);         # Legacy
161         $jv->schema->recursive_data_protection(...); # Recommended way
162
163   store
164         $store = $jv->store;
165
166       Holds a JSON::Validator::Store object that caches the retrieved
167       schemas.  This object will be shared amongst different "schema" objects
168       to prevent a schema from having to be downloaded again.
169
170   ua
171       Proxy attribute for "ua" in JSON::Validator::Store.
172

METHODS

174   bundle
175       This method can be used to get a bundled version of "schema". It will
176       however return a data-structure instead of a new object. See "bundle"
177       in JSON::Validator::Schema for an alternative.
178
179         # These two lines does the same
180         $data = $jv->bundle;
181         $data = $jv->schema->bundle->data;
182
183         # Recommended way
184         $schema = $jv->schema->bundle;
185
186   coerce
187       This attribute will be used as default value for "coerce" in
188       JSON::Validator::Schema. It is highly recommended to change this
189       directly on the "schema" instead:
190
191         $jv->coerce(...);         # Legacy
192         $jv->schema->coerce(...); # Recommended way
193
194   get
195       Proxy method for "get" in JSON::Validator::Schema.
196
197   new
198         $jv = JSON::Validator->new(%attributes);
199         $jv = JSON::Validator->new(\%attributes);
200
201       Creates a new JSON::Validate object.
202
203   load_and_validate_schema
204       This method will be deprecated in the future. See "errors" in
205       JSON::Validator::Schema and "is_invalid" in JSON::Validator::Schema
206       instead.
207
208   schema
209         $jv     = $jv->schema($json_or_yaml_string);
210         $jv     = $jv->schema($url);
211         $jv     = $jv->schema(\%schema);
212         $jv     = $jv->schema(JSON::Validator::Joi->new);
213         $jv     = $jv->schema(JSON::Validator::Schema->new);
214         $schema = $jv->schema;
215
216       Used to set a schema from either a data structure or a URL.
217
218       $schema will be an instance of JSON::Validator::Schema::Draft4,
219       JSON::Validator::Schema::Draft6 JSON::Validator::Schema::Draft7,
220       JSON::Validator::Schema::Draft201909,
221       JSON::Validator::Schema::OpenAPIv2, JSON::Validator::Schema::OpenAPIv3
222       or JSON::Validator::Schema.
223
224       The $url can take many forms, but needs to point to a text file in the
225       JSON or YAML format.
226
227       •   file://...
228
229           A file on disk. Note that it is required to use the "file" scheme
230           if you want to reference absolute paths on your file system.
231
232       •   http://... or https://...
233
234           A web resource will be fetched using the Mojo::UserAgent, stored in
235           "ua".
236
237       •   data://Some::Module/spec.json
238
239           Will load a given "spec.json" file from "Some::Module" using
240           "data_section" in JSON::Validator::Util.
241
242       •   data:///spec.json
243
244           A "data" URL without a module name will use the current package and
245           search up the call/inheritance tree.
246
247       •   Any other URL
248
249           An URL (without a recognized scheme) will be treated as a path to a
250           file on disk. If the file could not be found on disk and the path
251           starts with "/", then the will be loaded from the app defined in
252           "ua". Something like this:
253
254             $jv->ua->server->app(MyMojoApp->new);
255             $jv->ua->get('/any/other/url.json');
256
257   validate
258       Proxy method for "validate" in JSON::Validator::Schema.
259

COPYRIGHT AND LICENSE

289       Copyright (C) 2014-2021, Jan Henning Thorsen
290
291       This program is free software, you can redistribute it and/or modify it
292       under the terms of the Artistic License version 2.0.
293

AUTHOR

295       Jan Henning Thorsen - "jhthorsen@cpan.org"
296
297       Daniel Böhmer - "post@daniel-boehmer.de"
298
299       Ed J - "mohawk2@users.noreply.github.com"
300
301       Karen Etheridge - "ether@cpan.org"
302
303       Kevin Goess - "cpan@goess.org"
304
305       Martin Renvoize - "martin.renvoize@gmail.com"
306
307
308
309perl v5.34.0                      2022-01-21                JSON::Validator(3)