JSON::Validator::Schema(3pm)

1JSON::Validator::SchemaU(s3e)r Contributed Perl DocumentaJtSiOoNn::Validator::Schema(3)
2
3
4

NAME

6       JSON::Validator::Schema - Base class for JSON::Validator schemas
7

SYNOPSIS

9   Basics
10         # Create a new schema from a file on disk
11         # It is also possible to create the object from JSON::Validator::Schema,
12         # but you most likely want to use one of the subclasses.
13         my $schema = JSON::Validator::Schema::Draft7->new('file:///cool/beans.yaml');
14
15         # Validate the schema
16         die $schema->errors->[0] if $schema->is_invalid;
17
18         # Validate data
19         my @errors = $schema->validate({some => 'data'});
20         die $errors[0] if @errors;
21
22   Shared store
23         my $store = JSON::Validator::Store->new;
24         my $schema = JSON::Validator::Schema::Draft7->new(store => $store);
25
26         # Will not fetch the fike from web, if the $store has already retrived
27         # the schema
28         $schema->resolve('https://api.example.com/cool/beans.json');
29
30   Make a new validation class
31         package JSON::Validator::Schema::SomeSchema;
32         use Mojo::Base 'JSON::Validator::Schema';
33         has specification => 'https://api.example.com/my/spec.json#';
34         1;
35

DESCRIPTION

37       JSON::Validator::Schema is the base class for
38       JSON::Validator::Schema::Draft4, JSON::Validator::Schema::Draft6,
39       JSON::Validator::Schema::Draft7, JSON::Validator::Schema::Draft201909,
40       JSON::Validator::Schema::OpenAPIv2 and
41       JSON::Validator::Schema::OpenAPIv3.
42
43       Any of the classes above can be used instead of JSON::Validator if you
44       know which draft/version you are working with up front.
45
46   Validation
47       JSON::Validator::Schema can both validate user input and the schema
48       itself.
49
50       • A JSON::Validator::Schema represents a set of validation rules stored
51         in "data". The rules stored in the "data" attribute will be used when
52         calling the "validate" method.
53
54       • The input to "validate()" could be some data from a web request or
55         some other user input. "validate()" returns a list of
56         JSON::Validator::Error objects, if the user input (input to
57         "validate()") contains invalid data.
58
59       • The "errors" and "is_invalid" attributes has nothing to do with user
60         input, meaning it is not relevant for "validate". These two accessors
61         are used to check if the rules/schema stored in "data" is correct.
62         The validation is performed against the "specification". This is
63         pretty much the same as:
64
65           my $jv = JSON::Validator->new;
66           my $draft7 = $jv->schema('http://json-schema.org/draft-07/schema#')->schema;
67           my $schema = $jv->schema({name => {type => 'string'}})->schema;
68           my @errors = $draft7->validate($schema->data);
69

ATTRIBUTES

71   errors
72         $array_ref = $schema->errors;
73
74       Holds the errors after checking "data" against "specification".
75       $array_ref containing no elements means "data" is valid. Each element
76       in the array-ref is a JSON::Validator::Error object.
77
78       This attribute is not changed by "validate". It only reflects if the
79       $schema is valid.
80
81   formats
82         $hash_ref = $schema->formats;
83         $schema   = $schema->formats(\%hash);
84
85       Holds a hash-ref, where the keys are supported JSON type "formats", and
86       the values holds a code block which can validate a given format. A code
87       block should return "undef" on success and an error string on error:
88
89         sub { return defined $_[0] && $_[0] eq "42" ? undef : "Not the answer." };
90
91       See JSON::Validator::Formats for a list of supported formats.
92
93   recursive_data_protection
94       The value of this attribute will be copied into the created "schema".
95       See "recursive_data_protection" in JSON::Validator::Schema for more
96       details.
97
98   id
99         $str    = $schema->id;
100         $schema = $schema->id($str);
101
102       Holds the ID for this schema. Usually extracted from "$id" or "id" in
103       "data".
104
105   moniker
106         $str    = $schema->moniker;
107         $schema = $schema->moniker("some_name");
108
109       Used to get/set the moniker for the given schema. Will be "draft04" if
110       "specification" points to a JSON Schema draft URL, and fallback to
111       empty string if unable to guess a moniker name.
112
113       This attribute will (probably) detect more monikers from a given
114       "specification" or "/id" in the future.
115
116   recursive_data_protection
117         $schema = $schema->recursive_data_protection($bool);
118         $bool   = $schema->recursive_data_protection;
119
120       Recursive data protection is active by default, however it can be
121       deactivated by assigning a false value to the
122       "recursive_data_protection" attribute.
123
124       Recursive data protection can have a noticeable impact on memory usage
125       when validating large data structures. If you are encountering issues
126       with memory and you can guarantee that you do not have any loops in
127       your data structure then deactivating the recursive data protection may
128       help.
129
130       This attribute is EXPERIMENTAL and may change in a future release.
131
132       Disclaimer: Use at your own risk, if you have any doubt then don't use
133       it
134
135   specification
136         $str    = $schema->specification;
137         $schema = $schema->specification($str);
138
139       The URL to the specification used when checking for "errors". Usually
140       extracted from "$schema" or "schema" in "data".
141
142   store
143         $store = $schema->store;
144
145       Holds a JSON::Validator::Store object that caches the retrieved
146       schemas.  This object can be shared amongst different schema objects to
147       prevent a schema from having to be downloaded again.
148

METHODS

150   bundle
151         $bundled = $schema->bundle;
152
153       $bundled is a new JSON::Validator::Schema object where none of the
154       "$ref" will point to external resources. This can be useful, if you
155       want to have a bunch of files locally, but hand over a single file to a
156       client.
157
158         Mojo::File->new("client.json")
159           ->spurt(Mojo::JSON::to_json($schema->bundle->data));
160
161   coerce
162         $schema   = $schema->coerce('bool,def,num,str');
163         $schema   = $schema->coerce('booleans,defaults,numbers,strings');
164         $hash_ref = $schema->coerce;
165
166       Set the given type to coerce. Before enabling coercion this module is
167       very strict when it comes to validating types. Example: The string "1"
168       is not the same as the number 1, unless you have "numbers" coercion
169       enabled.
170
171       • booleans
172
173         Will convert what looks can be interpreted as a boolean (that is, an
174         actual numeric 1 or 0, and the strings "true" and "false") to a
175         JSON::PP::Boolean object. Note that "foo" is not considered a true
176         value and will fail the validation.
177
178       • defaults
179
180         Will copy the default value defined in the schema, into the input
181         structure, if the input value is non-existing.
182
183         Note that support for "default" is currently EXPERIMENTAL, and
184         enabling this might be changed in future versions.
185
186       • numbers
187
188         Will convert strings that looks like numbers, into true numbers. This
189         works for both the "integer" and "number" types.
190
191       • strings
192
193         Will convert a number into a string. This works for the "string"
194         type.
195
196   contains
197       This method will be removed in a future release.
198
199   data
200         my $hash_ref = $schema->data;
201         my $schema   = $schema->data($bool);
202         my $schema   = $schema->data($hash_ref);
203
204       Will set a structure representing the schema. In most cases you want to
205       use "resolve" instead of "data".
206
207   get
208         my $data = $schema->get([@json_pointer]);
209         my $data = $schema->get($json_pointer);
210         my $data = $schema->get($json_pointer, sub { my ($data, $json_pointer) = @_; });
211
212       This method will extract data from "data", using a $json_pointer - RFC
213       6901 <http://tools.ietf.org/html/rfc6901>. It can however be used in a
214       more complex way by passing in an array-ref: The array-ref can contain
215       "undef()" values, will result in extracting any element on that point,
216       regardsless of value. In that case a Mojo::Collection will be returned.
217
218       A callback can also be given. This callback will be called each time
219       the $json_pointer matches some data, and will pass in the $json_pointer
220       at that place.
221
222       In addition if this method "sees" a JSON-Schema $ref on the way, the
223       "$ref" will be followed into any given sub schema.
224
225   is_invalid
226         my $bool = $schema->is_invalid;
227
228       Returns true if the schema in "data" is invalid. Internally this method
229       calls "errors" which will validate "data" agains "specification".
230
231   load_and_validate_schema
232       This method is unsupported. Use "is_invalid" or "errors" instead.
233
234   new
235         my $schema = JSON::Validator::Schema->new($data);
236         my $schema = JSON::Validator::Schema->new($data, %attributes);
237         my $schema = JSON::Validator::Schema->new(%attributes);
238
239       Construct a new JSON::Validator::Schema object. Passing on $data as the
240       first argument will cause "resolve" to be called, meaning the
241       constructor might throw an exception if the schema could not be
242       successfully resolved.
243
244   resolve
245         $schema = $schema->resolve($uri);
246         $schema = $schema->resolve($data);
247
248       Used to resolve $uri or $data and store the resolved schema in "data".
249       If $data or $uri contains any $ref's, then these schemas will be
250       downloaded and resolved as well.
251
252       If "data" does not contain an "id" or "$id", then "id" will be assigned
253       a autogenerated "urn". This "urn" might be changed in future releases,
254       but should always be the same for the same "data".
255
256   schema
257       This method will be removed in a future release.
258
259   validate
260         @errors = $schema->validate($any);
261
262       Will validate $any against the schema defined in "data". Each element
263       in @errors is an JSON::Validator::Error object.
264

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SEE ALSO