NAME

Kernel::System::DataValidation – Backend to validate values via validator classes.

PUBLIC INTERFACE

Provides methods to either validate single values or complete data structures against validator classes for different purposes. The validators to be executed on the given values are grouped in an array consisting of either single strings (the validator name to be used) or hash elements including the validator name and further arguments if needed. Those modules are executed sequential.

In case all requested modules proceed successfully, the related method will return undef, otherwise it will either return an error object based on a single validation (in that case refer to Kernel::System::DataValidation::Error for more information), or it returns an errors object, that contains all collected error objects based on the data structure validation. In that case please refer to Kernel::System::DataValidation::Errors.

The different validator classes are located below Kernel::System::DataValidation::Validator::*, please refer to the single modules for more information about the usage.

Basically validators might be requested with or without passing arguments.

Validator without arguments:

    'ValidatorName' || { Validator => 'ValidatorName' }

Validator with arguments:

    {
        Validator => 'ValidatorName',
        Arguments => 'Argument1'
    }

    or

    {
        Validator => 'ValidatorName',
        Arguments => [ 'Argument1', 'Argument2' ... ]
    }

    or

    {
        Validator => 'ValidatorName',
        Arguments => {
            Argument1 => 'FirstArgumentValue',
            Argument2 => 'SecondArgumentValue',
            Argument3 =>  ...
        }
    }

The amount and needed type of the arguments relates to the particular validator. For more information about needed or optional arguments and their structure, please refer to the related validator module.

has Debug

Attribute that returns debug mode.

IsInvalidStructure()

Method that validates data structures based on validation schemata. A schema must be structured like:

    {
        AllowUnknownValues => 1,    # Allow given values, that don't exist in the schema. Default: 0
        Fields => {
            TicketID => [
                'Required',
                'Ticket::ID',
            ],
            ArticleID => [
                'Required',
                'Article::ID',
            ],
            Body => [
                'Required',
                { Validator => 'Pattern', Arguments => '.*' },
            ],
            ChatID => [
                'Required',
                'Chat::ChatID',
            ],
            ChatMessageID => [
                'Required',
                'Chat::ChatMessageID',
            ],
        },
    }

The data structure must be given as a hash reference (field names => values). The collected errors will be indicated by the given field names (keys).

    {
        TicketID  => 123,
        ArticleID => 123,
        Body      => 'This is a message body!',
    }

If the parameter AllowUnknownValues is set to true, the validation will ignore fields, without a valid schema entry. Otherwise it will result in an error UnknownValue.

    my $Errors = $DataValidationObject->IsInvalidStructure(
        Schema => {
            AllowUnknownValues => 1,    # Allow given values, that don't exist in the schema. Default: 0
            Fields => {
                TicketID => [
                    'Required',
                    { Validator => 'DataType', Arguments => 'PositiveInt' },
                    'Ticket::ID',
                ],
                ArticleID => [
                    'Required',
                    { Validator => 'DataType', Arguments => 'PositiveInt' },
                    'Article::ID',
                ],
                Body => [
                    'Required',
                    { Validator => 'Pattern', Arguments => '.*' },
                ],
            },
        },
        Values => {
            TicketID       => 123,
            ArticleID      => 123,
            Body           => 'This is a message body!',
            MyUnknownField => 'Field without a schema entry',
        }
    );

In case of errors, this method will return an errors object Kernel::System::DataValidation::Errors.

IsInvalid()

Method that validates single values against requested validators.

    my $Error = $DataValidationObject->IsInvalid(
        Validators => [
            'Required',
            'Ticket::TicketID',
        ],
        Value => 123,
    );

In case of errors, this method will return an error object Kernel::System::DataValidation::Error.