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

AUTHORS

295   Project Founder
296       Jan Henning Thorsen - "jhthorsen@cpan.org"
297
298   Contributors
299       • Aleksandr Orlenko
300
301       • Alexander Hartmaier
302
303       • Alexander Karelas
304
305       • Bernhard Graf
306
307       • Brad Barden
308
309       • Dagfinn Ilmari Mannsåker
310
311       • Daniel Böhmer
312
313       • David Cantrell
314
315       • Ed J
316
317       • Ere Maijala
318
319       • Fabrizio Gennari
320
321       • Ilya Rassadin
322
323       • Jason Cooper
324
325       • Karen Etheridge
326
327       • Kenichi Ishigaki
328
329       • Kevin M. Goess
330
331       • Kirill Matusov
332
333       • Krasimir Berov
334
335       • Lari Taskula
336
337       • Lee Johnson
338
339       • Martin Renvoize
340
341       • Mattias Päivärinta
342
343       • Michael Jemmeson
344
345       • Michael Schout
346
347       • Mohammad S Anwar
348
349       • Nick Morrott
350
351       • Pierre-Aymeric Masse
352
353       • Roy Storey
354
355       • Russell Jenkins
356
357       • Sebastian Riedel
358
359       • Stephan Hradek
360
361       • Tim Stallard
362
363       • Zoffix Znet
364
365
366
367perl v5.36.0                      2023-01-20                JSON::Validator(3)