The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


Params::Sah - Validate method/function parameters using Sah schemas


This document describes version 0.073 of Params::Sah (from Perl distribution Params-Sah), released on 2021-08-04.


 use Params::Sah qw(gen_validator);

 # for subroutines that accept positional parameters. all parameters required,
 # but you can pass undef to the third param.
 sub mysub1 {
     state $validator = gen_validator('str*', ['array*', min_len=>1], 'int');
 mysub1("john", ['a']);        # dies, the third argument is not passed
 mysub1("john", ['a'], 2);     # ok
 mysub1("john", ['a'], 2, 3);  # dies, extra parameter
 mysub1("john", ['a'], undef); # ok, even though the third argument is undef
 mysub1([],     ['a'], undef); # dies, first argument does not validate
 mysub1("john", [], undef);    # dies, second argument does not validate

 # for subroutines that accept positional parameters (this time arrayref instead
 # of array), some parameters optional. also this time we use 'allow_extra'
 # option to allow additional positional parameters.
 sub mysub1b {
     my $args = shift;
     state $validator = gen_validator({optional_params=>[2], allow_extra=>1}, 'str*', 'array*', 'int');
 mysub1b(["john", ['a']]);        # ok, the third argument is optional
 mysub1b(["john", ['a'], 2]);     # ok
 mysub1b(["john", ['a'], undef]); # ok
 mysub1b(["john", ['a'], 2, 3]);  # ok, extra params allowed

 # for subroutines that accept named parameters (as hash). all parameters
 # required, but you can pass undef to the 'age' parameter.
 sub mysub2 {
     my %args = @_;

     state $validator = gen_validator({named=>1}, name=>'str*', tags=>['array*', min_len=>1], age=>'int');
 mysub2(name=>"john", tags=>['a']);             # dies, the 'age' argument is not passed
 mysub2(name=>"john", tags=>['a'], age=>32);    # ok
 mysub2(name=>"john", tags=>['a'], age=>undef); # ok, even though the 'age' argument is undef
 mysub2(name=>[],     tags=>['a'], age=>undef); # dies, the 'name' argument does not validate
 mysub2(name=>"john", tags=>[],    age=>undef); # dies, the 'tags' argument does not validate

 # for subroutines that accept named parameters (this time as hashref). some
 # parameters optional. also this time we want to allow extra named parameters.
 sub mysub2b {
     my $args = shift;

     state $validator = gen_validator(
         {named=>1, optional_params=>['age'], allow_extra=>1},
         tags=>['array*', min_len=>1],
 mysub2b({name=>"john", tags=>['a']});                  # ok
 mysub2b({name=>"john", tags=>['a'], age=>32});         # ok
 mysub2b({name=>"john", tags=>['a'], age=>32, foo=>1}); # ok, extra param 'foo' allowed
 mysub2b({name=>"john", tags=>['a'], age=>undef});      # dies, this time, 'age' cannot be undef

Example with more complex schemas, with default value and coercion rules:

 sub mysub2c {
     my %args = @_;
     state $validator = gen_validator(
         {named => 1, optional_params => ['age']},
         name => ['str*', min_len=>4, match=>qr/\S/, default=>'noname'],
         age  => ['int', min=>17, max=>120],
         tags => ['array*', min_len=>1, of=>['str*', match=>qr/\A\w+\z/], 'x.perl.coerce_rules'=>['From_str::comma_sep']],
 mysub2c(tags=>['a']);                   # after validation, %args will be: (name=>'noname', tags=>['a'])
 mysub2c(name=>"mark", tags=>['b,c,d']); # after validation, %args will be: (name=>'mark', tags=>['b','c','d'])

Validator generation options:

 # default is to 'croak', valid values include: carp, die, warn, bool, str
 gen_validator({on_invalid=>'croak'}, ...);


This module provides a way for functions to validate their parameters using Sah schemas.



Bool. If set to true will print validator code when generated.


Str. Used to set default for backend option.


Bool. Used to set default for allow_extra option.


String. Used to set default for on_invalid option.


Bool. Used to set default for err_detail option.


Bool. Used to set default for disable option.


Bool. Used to set default for named option.


See benchmarks in Bencher::Scenarios::ParamsSah.


None exported by default, but exportable.

gen_validator([\%opts, ] ...) => code

Generate code for subroutine validation. It accepts an optional hashref as the first argument for options. The rest of the arguments are Sah schemas that correspond to the function parameters in the same position, i.e. the first schema will validate the function's first argument, and so on. Example:

 gen_validator('schema1', 'schema2', ...);
 gen_validator({option=>'val', ...}, 'schema1', 'schema2', ...);

Will return a coderef which is the validator code. The validator code accepts an arrayref (usually \@_). The validator code will by default croak on invalid parameters, but this behavior can be customized using the on_invalid option.

Known options:

  • backend => str (default: Data::Sah)

    Can be set to the experimental Data::Sah::Tiny to speed up validator generation for simpler schemas.

  • named => bool (default: 0)

    If set to true, it means we are generating validator for subroutine that accepts named parameters (e.g. f(name=>'val', other=>'val2')) instead of positional (e.g. f('val', 'val2')). The validator will accept the parameters as a hashref. And the arguments of gen_validator are assumed to be a hash of parameter names and schemas instead of a list of schemas, for example:

     gen_validator({named=>1}, arg1=>'schema1', arg2=>'schema2', ...);
  • optional_params => array

    By default all parameters are required. This option specifies which parameters should be made optional. For positional parameters, specify the index (0-based).

  • allow_extra => bool (default: 0)

    If set to one then additional positional or named parameters are allowed (and not validated). By default, no extra parameters are allowed.

  • on_invalid => str (default: 'croak')

    What should the validator code do when function parameters are invalid? The default is to croak (see Carp) to report error to STDERR from the caller perspective. Other valid choices include: warn, carp, die, bool (return false on invalid, or true on valid), str (return an error message on invalid, or empty string on valid).

  • invalid_detail => bool (default: 0)

    If set to true, will generate a more detailed error message. For example, with this schema:

     [str => {min_len=>4}]

    then the string 'foo' will fail to validate with this error message "Length must be at least 4". Otherwise, the error message will just be something like: "Fail schema ['str', {min_len=>1}]". By default this option is set to false for slightly faster validation.

  • disable => bool (default: 0)

    If set to 1, will return an empty coderef validator. Used to disable parameter checking. Usually via setting "$OPT_DISABLE" to disable globally.


How do I learn more about Sah (the schema language)?

See the specification: Sah. The Sah::Examples distribution also contains more examples. Also, for other examples, lots of my distributions contain Rinci metadata which includes schemas for each function arguments.

Why does the validator code accept arrayref/hashref instead of array/hash?

To be able to modify the original array/hash, e.g. set default value.

What if my subroutine accepts a mix of positional and named parameters?

You can put all your parameters in a hash first, then feed it to the validator. For example:

 sub mysub {
     my %args;
     %args = %{shift} if req $_[0] eq 'HASH'; # accept optional hashref
     ($args{x}, $args{y}) = @_; # positional params
     state $validator = gen_validator(
         {named=>1, optional_params=>['opt1','opt2']},
 mysub(1, -2);                # ok, after validation %args will become (x=>1, y=>-2)
 mysub({}, 1, -2);            # ok, after validation %args will become (x=>1, y=>-2)
 mysub({opt1=>"foo"}, 1, -2); # ok, after validation %args will become (x=>1, y=>-2, opt1=>"foo")
 mysub({opt3=>"foo"}, 1, -2); # dies, unknown option 'opt3'
 mysub({opt1=>"foo"}, 1);     # dies, missing required arg 'x'
 mysub({opt1=>[]}, 1, -2);    # dies, 'opt1' argument doesn't validate

How to give default value to parameters?

By using the Sah default clause in your schema:

 gen_validator(['str*', default=>'green']);

How to make some parameters optional?

By using the optional_params option, which is an array of parameter names to make optional. To set a positional parameter optional, specify its index (0-based) as name.

Why is my program failing with error message: Can't call method "state" on an undefined value?

You need to specify that you want to use state variables, either by:

 # at least
 use 5.010;


 use feature 'state';

How do I see the validator code being generated?

Set $Params::Sah::DEBUG=1 before gen_validator(), for example:

 use Params::Sah qw(gen_validator);

 $Params::Sah::DEBUG = 1;
 gen_validator('int*', 'str');

Sample output:

   1|sub(\@) {
   2|    my $_ps_args = shift;
   3|    my $_ps_res;
   6|    ### validating 0:
   7|    no warnings 'void';
   8|    my $_sahv_dpath = [];
   9|    Carp::croak("arg0: $_ps_res") if !(    # req #0
  10|    ((defined($_ps_args->[0])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Required but not specified"),0))
  12|    &&
  14|    # check type 'int'
  15|    ((Scalar::Util::Numeric::isint($_ps_args->[0])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Not of type integer"),0)));
  18|    ### validating 1:
  19|    Carp::croak("arg1: $_ps_res") if !(    # skip if undef
  20|    (!defined($_ps_args->[1]) ? 1 :
  22|    (# check type 'str'
  23|    ((!ref($_ps_args->[1])) ? 1 : (($_ps_res //= (@$_sahv_dpath ? '@'.join("/",@$_sahv_dpath).": " : "") . "Not of type text"),0)))));
  24|    return;


Please visit the project's homepage at


Source repository is at


Please report any bugs or feature requests on the bugtracker website

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.


Sah, Data::Sah

Alternative non-Sah modules: Params::ValidationCompiler (a compiled version of Params::Validate), Type::Params (from Type::Tiny).

Alternative Sah modules: you can add Rinci metadata to your function, then use Perinci::Sub::Wrapper or Perinci::CmdLine to enforce validation. These can do more then schema checking e.g. interargument relationship checking, external dependency checking, etc.


perlancar <>


This software is copyright (c) 2021, 2020, 2016, 2015 by

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.