1Validation::Class::WhitUespearpeCro(n3t)ributed Perl DocVuamleindtaattiioonn::Class::Whitepaper(3)
2
6 Validation::Class::Whitepaper - Operate with Impunity
7
9 version 7.900058
10
12 This whitepaper will serves as a guide to help readers understand the
13 common data validation issues as well as the the rationale and various
14 usage scenarios for Validation::Class.
15 Data validation is an important aspect of every application yet it is
17 often overlooked or neglected. Data validation should be thought of as
18 your data input firewall, a layer that exist between the user of your
19 application and the application's business objects.
20
22 The most common application security weakness is the failure to
23 properly validate input from the client or environment. Data validation
24 is important because it provides security, it allows you to ensure user
25 supplied data is formatted properly, is within length boundaries,
26 contains permitted characters and adheres to business rules.
27 To understand the problem domain we need to first ask ourselves:
29 * what is data validation? and ... is that what I've been doing?
31 * what are the common data validation requirements?
32 * what are the common use-cases where validation becomes tricky?
33 Data validation is the process of auditing a piece of data to ensure it
35 fits a specific criteria. Standard data validation requirements are:
36 * existence checking
38 * range checking
39 * type checking
40 * list-lookup checking
41 * dependency checking
42 * pattern checking
43 * custom validation checking (business logic)
44 Typically when designing an application we tend to name input
46 parameters in an arbitrarily fashion and validate the same data at
47 various stages during a program's execution (duplicating logic and
48 validation routines) in various places in the application stack. This
49 approach is inefficient and prone to bugs, inconsistencies and security
50 problems.
51 Data can be submitted to an application in various formats and it is
53 not always ideal, and the option to pre-format the data is not always
54 ideal or even possible. A few common use-cases were validation is
55 required and often fails (in a big big way) are as follows:
56 * handling arbitrarily and/or dynamically-named parameters
58 * handling input for batch-processing
59 * handling multi-type parameters (array or scalar depending on context)
60 * handling complex conditional validation logic
61 * handling multi-variant parameter names (aliases)
62 * handling parameter dependencies
63 * handling errors (reporting messages, localization, etc)
64
66 A better approach to data validation is to first consider each
67 parameter hitting your application as a transmission fitting a very
68 specific criteria and construct a data validation layer that operates
69 with that in mind (e.g. exactly like a network firewall). Your data
70 validation rules should act as filters which will accept or reject and
71 format the transmission for use within your application.
72 A proper validation framework should allow you to model data and
74 construct validation objects with a focus on structuring rules, reusing
75 common declarations, defining input filters and validating data. Its
76 main purpose should be to properly handle data input errors. It's
77 ulterior motive should be to ensure consistency and promote reuse of
78 data validation rules.
79
81 Validation::Class was built around the concept of compartmentalization
82 and re-use. That premise gave birth to the idea of persistent data
83 validation rules which exist in a class configuration which is
84 associated with a class which acts as a validation domain for related
85 validation rules.
86 Validation classes derived from Validation::Class are typically
88 configured using the Validation::Class sugar functions (or keywords).
89 Validation classes are typically defined using the following keywords:
90 * field - a data validation rule that matches an input parameter
92 * mixin - a configuration template which can be merged with a field
93 * directive - a field/mixin rule corresponding to a directive class name
94 * filter - a custom filtering routine which transforms a field value
95 * method - a self-validating sub-routine w/ associated validation profile
96 A data validation framework exists to handle failures, it is its main
98 function and purpose, in-fact, the difference between a validation
99 framework and a type-constraint system is how it responds to errors.
100 There are generally two types of errors that occur in an application,
102 user-errors which are expected and should be handled and reported so
103 that a user can correct the problem, and system-errors which are
104 unexpected and should cause the application to terminate and/or
105 handling the exception. Exception handling is the process of responding
106 to the occurrence, during computation, of exceptions (anomalous or
107 exceptional situations).
108 User errors and system errors are poplar opposites. It is not always
110 desired and/or appropriate to crash from a failure to validate user
111 input. The following examples should clearly display how
112 Validation::Class addresses key pain-points and handles common use-
113 cases were validation is usually quite arduous.
114 Dynamic Parameters
116 # handling arbitrary and/or dynamically-named parameters
117 package DynamicParameters;
119 use Validation::Class;
121 field email => {
123 required => 1,
124 pattern => qr/\@localhost$/
125 };
126 field login => {
128 required => 1,
129 min_length => 5,
130 alias => ['user']
131 };
132 field password => {
134 required => 1,
135 min_length => 5,
136 min_digits => 1,
137 alias => ['pass']
138 };
139 package main;
141 my $params = {
143 user => 'admin', # arbitrary
144 pass => 's3cret', # arbitrary
145 email_1 => 'admin@localhost', # dynamic created
146 email_2 => 'root@localhost', # dynamic created
147 email_3 => 'sa@localhost', # dynamic created
148 };
149 my $dp = DynamicParameters->new(params => $params);
151 $dp->proto->clone_field('email', $_)
153 for $dp->params->grep(qr/^email/)->keys
154 ;
155 print $dp->validate ? "OK" : "NOT OK";
157 1;
159 Batch-Processing
161 # handling input for batch-processing
162 package BatchProcessing;
164 use Validation::Class;
166 mixin scrub => {
168 required => 1,
169 filters => ['trim', 'strip']
170 };
171 field header => {
173 mixin => 'scrub',
174 options => ['name', 'email', 'contact', 'dob', 'country'],
175 multiples => 1 # handle param as a scalar or arrayref
176 };
177 field name => {
179 mixin => 'scrub',
180 filters => ['titlecase'],
181 min_length => 2
182 };
183 field email => {
185 mixin => 'scrub',
186 min_length => 3
187 };
188 field contact => {
190 mixin => 'scrub',
191 length => 10
192 };
193 field dob => {
195 mixin => 'scrub',
196 length => 8,
197 pattern => '##/##/##'
198 };
199 field country => {
201 mixin => 'scrub'
202 };
203 package main;
205 my $params = {
207 pasted_data => q{
208 name email contact dob country
209 john john@zuzu.com 9849688899 12/05/98 UK
210 jim kathy kjim@zuz.com 8788888888 05/07/99 India
211 Federar fed@zuzu.com 4484848989 11/21/80 USA
212 Micheal micheal@zuzu.com 6665551212 06/10/87 USA
213 Kwang Kit kwang@zuzu.com 7775551212 07/09/91 India
214 Martin jmartin@zuzu.com 2159995959 02/06/85 India
215 Roheeth roheeth@zuzu.com 9596012020 01/10/89 USA
216 }
217 };
218 # ... there are many ways this could be parsed and validated
220 # ... but this is simple
221 my $bpi = my @pasted_lines = map { s/^\s+//; $_ } split /\n/, $params->{pasted_data};
223 my @headers = split /\t/, shift @pasted_lines;
224 my $bp = BatchProcessing->new(params => { header => [@headers] });
226 # validate headers first
228 if ($bp->validate) {
230 $bp->params->clear;
232 $bpi--;
234 # validate each line, halt on first bad line
236 while (my $line = shift @pasted_lines) {
238 my @data = split /\t/, $line;
240 for (my $i=0; $i<@data; $i++) {
242 $bp->params->add($headers[$i], $data[$i]);
244 }
246 last unless $bp->validate;
248 $bp->params->clear;
250 $bpi--;
252 }
254 }
256 print ! $bpi ? "OK" : "NOT OK";
258 1;
260 Multi-Type Parameters
262 # handling multi-type parameters (array or scalar depending on context)
263 package MultiType;
265 use Validation::Class;
267 field letter_type => {
269 required => 1,
271 options => [ 'A' .. 'Z' ],
272 multiples => 1 # turn on multi-type processing
273 };
275 package main;
277 my $mt = MultiType->new;
279 my $ok = 0;
280 $mt->params->add(letter_type => 'A');
282 $ok++ if $mt->validate;
284 $mt->params->clear->add(letter_type => ['A', 'B', 'C']);
286 $ok++ if $mt->validate;
288 print $ok == 2 ? "OK" : "NOT OK";
290 1;
292 Complex Conditions
294 # handling complex conditional validation logic
295 package ComplexCondition;
297 use Validation::Class;
299 mixin scrub => {
301 required => 1,
302 filters => ['trim', 'strip']
303 };
304 mixin flag => {
306 length => 1,
307 options => [0, 1]
308 };
309 field first_name => {
311 mixin => 'scrub',
312 filters => ['titlecase']
313 };
314 field last_name => {
316 mixin => 'scrub',
317 filters => ['titlecase']
318 };
319 field role => {
321 mixin => 'scrub',
322 filters => ['titlecase'],
323 options => ['Client', 'Employee', 'Administrator'],
324 default => 'Client'
325 };
326 field address => {
328 mixin => 'scrub',
329 required => 0,
330 depends_on => ['city', 'state', 'zip']
331 };
332 field city => {
334 mixin => 'scrub',
335 required => 0,
336 depends_on => 'address'
337 };
338 field state => {
340 mixin => 'scrub',
341 required => 0,
342 length => '2',
343 pattern => 'XX',
344 depends_on => 'address'
345 };
346 field zip => {
348 mixin => 'scrub',
349 required => 0,
350 length => '5',
351 pattern => '#####',
352 depends_on => 'address'
353 };
354 field has_mail => {
356 mixin => 'flag'
357 };
358 profile 'registration' => sub {
360 my ($self) = @_;
362 # address info not required unless role is client or has_mail is true
364 return unless $self->validate('has_mail');
366 $self->queue(qw/first_name last_name/);
368 if ($self->param('has_mail') || $self->param('role') eq 'Client') {
370 # depends_on directive kinda makes city, state and zip required too
372 $self->queue(qw/+address/);
373 }
375 my $ok = $self->validate;
377 $self->clear_queue;
379 return $ok;
381 };
383 package main;
385 my $ok = 0;
387 my $mt;
388 $mt = ComplexCondition->new(
390 first_name => 'Rachel',
391 last_name => 'Green'
392 );
393 # defaults to client, missing address info
395 $ok++ if ! $mt->validate_profile('registration');
396 $mt = ComplexCondition->new(
398 first_name => 'monica',
399 last_name => 'geller',
400 role => 'employee'
401 );
402 # filters (pre-process) role and titlecase, as employee no address needed
404 $ok++ if $mt->validate_profile('registration');
405 $mt = ComplexCondition->new(
407 first_name => 'phoebe',
408 last_name => 'buffay',
409 address => '123 street road',
410 city => 'nomans land',
411 state => 'zz',
412 zip => '54321'
413 );
414 $ok++ if $mt->validate_profile('registration');
416 print $ok == 3 ? "OK" : "NOT OK";
418 1;
420 Multi-Variant Parameters
422 # handling multi-variant parameter names (aliases)
423 package MultiName;
425 use Validation::Class;
427 field login => {
429 required => 1,
431 min_length => 5, # must be 5 or more chars
432 min_alpha => 1, # must have at-least 1 alpha char
433 min_digits => 1, # must have at-least 1 digit char
434 min_symbols => 1, # must have at-least 1 non-alphanumeric char
435 alias => [
436 'signin',
437 'username',
438 'email',
439 'email_address'
440 ]
441 };
443 package main;
445 my $ok = 0;
447 # fail
449 $ok++ if ! MultiName->new(login => 'miso')->validate;
450 # nice
452 $ok++ if MultiName->new(login => 'm!s0_soup')->validate;
453 # no signin field exists, however, the alias directive pre-processing DWIM
455 $ok++ if MultiName->new(signin => 'm!s0_soup')->validate;
456 # process aliases
458 $ok++ if MultiName->new(params => {signin => 'm!s0_soup'})->validate;
459 $ok++ if MultiName->new(params => {username => 'm!s0_soup'})->validate;
460 $ok++ if MultiName->new(params => {email => 'm!s0_soup'})->validate;
461 $ok++ if MultiName->new(params => {email_address => 'm!s0_soup'})->validate;
462 print $ok == 7 ? "OK" : "NOT OK";
464 1;
466 Parameter Dependencies
468 # handling parameter dependencies
469 package ParamDependencies;
471 use Validation::Class;
473 mixin scrub => {
475 required => 1,
476 filters => ['trim', 'strip']
477 };
478 mixin flag => {
480 length => 1,
481 options => [0, 1]
482 };
483 field billing_address => {
485 mixin => 'scrub',
486 required => 1,
487 depends_on => ['billing_city', 'billing_state', 'billing_zip']
488 };
489 field billing_city => {
491 mixin => 'scrub',
492 required => 0,
493 depends_on => 'billing_address'
494 };
495 field billing_state => {
497 mixin => 'scrub',
498 required => 0,
499 length => '2',
500 pattern => 'XX',
501 depends_on => 'billing_address'
502 };
503 field billing_zip => {
505 mixin => 'scrub',
506 required => 0,
507 length => '5',
508 pattern => '#####',
509 depends_on => 'billing_address'
510 };
511 field shipping_address => {
513 mixin_field => 'billing_address',
514 depends_on => ['shipping_city', 'shipping_state', 'shipping_zip']
515 };
516 field shipping_city => {
518 mixin_field => 'billing_city',
519 depends_on => 'shipping_address'
520 };
521 field shipping_state => {
523 mixin_field => 'billing_state',
524 depends_on => 'shipping_address'
525 };
526 field shipping_zip => {
528 mixin_field => 'billing_zip',
529 depends_on => 'shipping_address'
530 };
531 field same_billing_shipping => {
533 mixin => 'flag'
534 };
535 profile 'addresses' => sub {
537 my ($self) = @_;
539 return unless $self->validate('same_billing_shipping');
541 # billing and shipping address always required
543 $self->validate(qw/+billing_address +shipping_address/);
544 # address must match if option is selected
546 if ($self->param('same_billing_shipping')) {
547 foreach my $param ($self->params->grep(qr/^shipping_/)->keys) {
549 my ($suffix) = $param =~ /^shipping_(.*)/;
551 my $billing = $self->param("billing_$suffix");
553 my $shipping = $self->param("shipping_$suffix");
554 # shipping_* must match billing_*
556 unless ($billing eq $shipping) {
557 $self->errors->add(
558 "Billing and shipping addresses do not match"
559 );
560 last;
561 }
562 }
564 }
566 return $self->error_count ? 0 : 1;
568 };
570 package main;
572 my $ok = 0;
574 my $pd;
575 $pd = ParamDependencies->new(
577 billing_address => '10 liberty boulevard',
578 billing_city => 'malvern',
579 billing_state => 'pa',
580 billing_zip => '19355'
581 );
582 # missing shipping address info
584 $ok++ if ! $pd->validate_profile('addresses');
585 $pd = ParamDependencies->new(
587 billing_address => '10 liberty boulevard',
588 billing_city => 'malvern',
589 billing_state => 'pa',
590 billing_zip => '19355',
591 shipping_address => '301 cherry street',
593 shipping_city => 'pottstown',
594 shipping_state => 'pa',
595 shipping_zip => '19464'
596 );
597 $ok++ if $pd->validate_profile('addresses');
599 $pd = ParamDependencies->new(
601 billing_address => '10 liberty boulevard',
602 billing_city => 'malvern',
603 billing_state => 'pa',
604 billing_zip => '19355',
605 same_billing_shipping => 1,
607 shipping_address => '301 cherry street',
609 shipping_city => 'pottstown',
610 shipping_state => 'pa',
611 shipping_zip => '19464'
612 );
613 # billing and shipping don't match
615 $ok++ if ! $pd->validate_profile('addresses');
616 $pd = ParamDependencies->new(
618 billing_address => '10 liberty boulevard',
619 billing_city => 'malvern',
620 billing_state => 'pa',
621 billing_zip => '19355',
622 same_billing_shipping => 1,
624 shipping_address => '10 liberty boulevard',
626 shipping_city => 'malvern',
627 shipping_state => 'pa',
628 shipping_zip => '19355'
629 );
630 $ok++ if $pd->validate_profile('addresses');
632 print $ok == 4 ? "OK" : "NOT OK";
634 1;
636
638 If you are looking for a simple way to get started with
639 Validation::Class, please review Validation::Class::Simple. The
640 instructions contained there are also relevant for configuring any
641 class derived from Validation::Class.
642
644 The following screencast <http://youtu.be/YCPViiB5jv0> and/or slideshow
645 <http://www.slideshare.net/slideshow/embed_code/9632123> explains what
646 Validation::Class is, why it was created, and what it has to offer.
647 Please note that this screencast and slideshow was created many moons
648 ago and some of its content may be a bit outdated.
649
651 Al Newkirk <anewkirk@ana.io>
652
654 This software is copyright (c) 2011 by Al Newkirk.
655 This is free software; you can redistribute it and/or modify it under
657 the same terms as the Perl 5 programming language system itself.
658perl v5.36.0 2022-07-22 Validation::Class::Whitepaper(3)