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

METHODS

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

NAME

SYNOPSIS

DESCRIPTION

ATTRIBUTES

METHODS

SEE ALSO