Name

Params::Validate::Strict - Validates a set of parameters against a schema

Version

Version 0.43

Synopsis

my $schema = {
    username => { type => 'string', min => 3, max => 50 },
    age => { type => 'integer', min => 0, max => 150 },
};

my $input = {
     username => 'john_doe',
     age => '30',   # Will be coerced to integer
};

my $validated_input = validate_strict(schema => $schema, input => $input);

if(defined($validated_input)) {
    print "Example 1: Validation successful!\n";
    print 'Username: ', $validated_input->{username}, "\n";
    print 'Age: ', $validated_input->{age}, "\n";   # It's an integer now
} else {
    print "Example 1: Validation failed: $@\n";
}

Upon first reading this may seem overly complex and full of scope creep in a sledgehammer to crack a nut sort of way, however two use cases make use of the extensive logic that comes with this code and I have a couple of other reasons for writing it.

Methods

Validate_Strict

Validates a set of parameters against a schema.

This function takes two mandatory arguments:

It takes optional arguments:

The schema can define the following rules for each parameter:

Api Specification

Input
{
    schema                    => { type => ['hashref', 'arrayref'] },   # or members
    input                     => { type => ['hashref', 'arrayref'] },   # or args
    description               => { type => 'string',  optional => 1 },
    custom_types              => { type => 'hashref', optional => 1 },
    unknown_parameter_handler => { type => 'string',  optional => 1,
                                   memberof => ['die', 'warn', 'ignore'] },
    logger                    => { type => 'object',  optional => 1, can => ['error', 'warn'] },
    relationships             => { type => 'arrayref', optional => 1 },
    cross_validation          => { type => 'hashref', optional => 1 },
}

The arguments may be passed as a list of key/value pairs or as a single hashref. A hashref input is validated as named parameters; an arrayref input is validated as positional parameters, in which case every parameter in the schema needs a position.

Output
{ type => 'hashref' }

A new hashref of the validated and coerced parameters, keyed by canonical parameter name. It croaks (or calls $logger->error and then croaks) on the first validation failure.

Example Usage

my $schema = {
  host => { type => 'string' },
  port => { type => 'integer' },
  ssl => { type => 'boolean' },
  file => { type => 'string', optional => 1 },
  content => { type => 'string', optional => 1 }
};

my $relationships = [
  {
    type => 'mutually_exclusive',
    params => ['file', 'content']
  }, {
    type => 'required_group',
    params => ['host', 'file']
  },
  {
    type => 'dependency',
    param => 'port',
    requires => 'host'
  },
  {
    type => 'value_constraint',
    if => 'ssl',
    then => 'port',
    operator => '==',
    value => 443
  }
];

my $validated = validate_strict(
  schema => $schema,
  input => $input,
  relationships => $relationships
);

Migration From Legacy Validators

From Params::Validate

# Old style
validate(@_, {
    name => { type => SCALAR },
    age => { type => SCALAR, regex => qr/^\d+$/ }
});

# New style
validate_strict(
    schema => {     # or "members"
        name => 'string',
        age => { type => 'integer', min => 0 }
    },
    args => { @_ }
);

From Type::Params

# Old style
my ($name, $age) = validate_positional \@_, Str, Int;

# New style - requires converting to named parameters first
my %args = (name => $_[0], age => $_[1]);
my $validated = validate_strict(
    schema => { name => 'string', age => 'integer' },
    args => \%args
);

Compile_Schema

my $validator = compile_schema(\%schema);
my $result    = $validator->(\%input);

# with optional keyword args
my $validator = compile_schema(\%schema,
    description            => 'User registration',
    custom_types           => \%types,
    unknown_parameter_handler => 'warn',
);

Pre-captures a schema (and any optional keyword arguments accepted by validate_strict) into a reusable validator closure. Calling the returned coderef is equivalent to:

validate_strict(schema => \%schema, input => \%input, %opts);

but the schema is analysed once, when compile_schema is called, rather than on every call - useful when the same schema is applied repeatedly in a hot path. The result, the errors raised, the warnings and the logger calls are exactly those of validate_strict; only the speed differs.

Fields that use a built-in type (string, integer, number, boolean, arrayref, hashref, scalar, coderef, object and their synonyms) with any of the rules min, max, optional, nullable, default, description, error_msg, matches, memberof (also enum and values) and case_sensitive are validated by a fast path. Any other field - one that uses callback, transform, union types, aliases, needs, nested schema, custom types, the class and element rules, and so on - is validated by the general code, as before, so using such a rule never changes behaviour; it just does not get faster. Positional schemas (those with position) are not precompiled. On a typical five-field schema a compiled validator runs about three times faster than calling validate_strict directly.

The schema must not be modified after it has been compiled, since what was learnt about it is kept. Compile a new validator instead.

Arguments

Returns

A code reference sub ($input) -> \%validated.

Api Specification

Input
{
    schema => { type => ['hashref', 'arrayref'] },
    opts   => { type => 'hashref', optional => 1 },   # passed as trailing key/value pairs
}
Output
{ type => 'coderef' }

The returned coderef has the signature sub ($input) -> \%validated, and croaks in the same way as validate_strict.

Author

Nigel Horne, <njh at nigelhorne.com>

Formal Specification

[PARAM_NAME, VALUE, TYPE_NAME, CONSTRAINT_VALUE]

ValidationRule ::= SimpleType | ComplexRule | UnionType

SimpleType ::= string | integer | number | float | boolean | scalar
           | scalarref | stringref | arrayref | hashref | coderef
           | object | void | regex | handle
           | arraylike | hashlike | codelike | invocant

UnionType ::= seq SimpleType    -- at least two members; written as type => ['a', 'b']

ComplexRule == [
    type: SimpleType | UnionType;
    min: ℕ₁;
    max: ℕ₁;
    optional: 𝔹;
    matches: REGEX;
    regex: REGEX;
    nomatch: REGEX;
    memberof: seq VALUE;
    enum: seq VALUE;
    values: seq VALUE;
    notmemberof: seq VALUE;
    callback: FUNCTION;
    isa: TYPE_NAME;
    does: ROLE_NAME;
    can: METHOD_NAME | seq METHOD_NAME;
    classisa: TYPE_NAME;
    subclass: TYPE_NAME;
    classdoes: ROLE_NAME;
    classcan: METHOD_NAME | seq METHOD_NAME;
    element_isa: TYPE_NAME;
    needs: PARAM_NAME | seq PARAM_NAME;
    driver: TYPE_NAME;
    semantic: 'unix_timestamp' | 'identifier' | 'class_name' | 'filename';
    aliases: seq PARAM_NAME;
    slurp: 𝔹;
    position: ℕ₀;
    default: VALUE;
    transform: FUNCTION;
    error_msg: STRING
]

Schema == PARAM_NAME ⇸ ValidationRule

Arguments == PARAM_NAME ⇸ VALUE

ValidatedResult == PARAM_NAME ⇸ VALUE

∀ rule: ComplexRule •
  rule.min ≤ rule.max ∧
  ¬((rule.memberof ∨ rule.enum ∨ rule.values) ∧ rule.min) ∧
  ¬((rule.memberof ∨ rule.enum ∨ rule.values) ∧ rule.max) ∧
  ¬(rule.notmemberof ∧ rule.min) ∧
  ¬(rule.notmemberof ∧ rule.max)

∀ schema: Schema; args: Arguments •
  dom(validate_strict(schema, args)) ⊆ dom(schema) ∪ dom(args)

validate_strict: Schema × Arguments → ValidatedResult

∀ schema: Schema; args: Arguments •
  let result == validate_strict(schema, args) •
    (∀ name: dom(schema) ∩ dom(args) •
      name ∈ dom(result) ⇒
      type_matches(result(name), schema(name))) ∧
    (∀ name: dom(schema) •
      ¬optional(schema(name)) ⇒ name ∈ dom(args))

type_matches: VALUE × ValidationRule → 𝔹

Example

use Params::Get;
use Params::Validate::Strict;

sub where_am_i
{
    my $params = Params::Validate::Strict::validate_strict({
        args => Params::Get::get_params(undef, \@_),
        description => 'Print a string of latitude and longitude',
        error_msg => 'Latitude is a number between +/- 90, longitude is a number between +/- 180',
        members => {
            'latitude' => {
                type => 'number',
                min => -90,
                max => 90
            }, 'longitude' => {
                type => 'number',
                min => -180,
                max => 180
            }
        }
    });

    print 'You are at ', $params->{'latitude'}, ', ', $params->{'longitude'}, "\n";
}

where_am_i({ latitude => 3.14, longitude => -155 });

Bugs

Known limitations:

Please report any other bugs as described in "SUPPORT".

Security

Taint Mode

This module does not untaint its return values. When running under Perl's taint mode (-T), any value that was derived from tainted external input ($ENV{}, STDIN, etc.) will remain tainted in the validated result, even if the module accepted it. Callers that require untainted values must perform their own regex capture after validation, for example:

my $validated = validate_strict(%args);
my ($safe_name) = ($validated->{name} =~ /\A([\w\s]+)\z/);

User-Supplied Regex Patterns

The matches rule accepts pre-compiled qr// objects supplied by the caller. A pathologically constructed pattern (e.g. qr/(a+)+b/) can cause catastrophic backtracking and peg a CPU core when matched against a hostile input value. Use possessive quantifiers (++) or atomic groups ((?>...)) in any matches pattern that will be applied to untrusted data.

Error Message Content

Error and warning messages produced by this module may include the parameter value supplied by the caller. The module strips ASCII control characters (including CR and LF) from all messages before passing them to the logger or croaking, to prevent log-injection and HTTP response-splitting attacks. Callers should nevertheless apply their own output encoding before including any validated value in an HTTP response, HTML page, or structured log entry.

See Also

Support

This module is provided as-is without any warranty.

Please report any bugs or feature requests to bug-params-validate-strict at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Params-Validate-Strict. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

You can find documentation for this module with the perldoc command.

perldoc Params::Validate::Strict

You can also look for information at:

Copyright 2025-2026 Nigel Horne.

This program is released under the following licence: GPL2. If you use it, please let me know.