NAME

GDPR::IAB::TCFv2::Validator - declarative compliance checks for TC strings

SYNOPSIS

use GDPR::IAB::TCFv2::Validator;

my $validator = GDPR::IAB::TCFv2::Validator->new(
    vendor_id                       => 284,
    consent_purpose_ids             => [ 1, 3, 9 ],
    legitimate_interest_purpose_ids => [ 10 ],
    flexible_purpose_ids            => [ 10 ],
    check_disclosed_vendors         => 1,
);

# Fail-fast: stops at the first failing rule.
my $result = $validator->validate($tc_string);

# Accumulate every failure for richer error reporting.
my $result = $validator->validate_all($tc_string);

if ($result) {
    # All rules passed.
}
else {
    warn "Compliance failed:\n$result\n";  # stringification = reasons
    for my $reason ( $result->reasons ) {
        log_failure($reason);
    }
}

DESCRIPTION

GDPR::IAB::TCFv2::Validator is a small rule engine that turns a static "compliance policy" — required purposes, expected vendor, optional disclosed-vendors check — into a single validate / validate_all call against a TC string (or a pre-parsed GDPR::IAB::TCFv2 object).

Each rule produces a human-readable reason on failure; reasons are collected on a GDPR::IAB::TCFv2::Validator::Result object that overloads boolean and string contexts so it drops into typical error-handling idioms (if (!$result), print "$result\n") without ceremony.

CONSTRUCTOR

new

my $v = GDPR::IAB::TCFv2::Validator->new( %args );

Recognized keys:

• vendor_id — the vendor whose access is being validated. Optional in the constructor (can be supplied per call via validate(..., vendor_id => N)) but one of the two must be set or validate/validate_all will croak with "missing vendor_id".

• consent_purpose_ids — arrayref of purpose IDs that must have vendor consent. Validated via "is_vendor_consent_allowed" in GDPR::IAB::TCFv2.

• legitimate_interest_purpose_ids — arrayref of purpose IDs that must have vendor legitimate-interest. Validated via "is_vendor_legitimate_interest_allowed" in GDPR::IAB::TCFv2. The IAB spec forbids LI for Purpose 1 always, and for Purposes 3-6 in TCF v2.2+; those are enforced by the underlying parser and surface here as failures.

• flexible_purpose_ids — arrayref of purpose IDs that are flexible per the vendor's GVL declaration (the basis can flip if a publisher restriction is present in the TC string). The default basis is derived structurally from the other two lists:

  • If the purpose ID also appears in consent_purpose_ids, the default basis is consent.

  • If the purpose ID also appears in legitimate_interest_purpose_ids, the default basis is legitimate interest.

  A purpose listed in flexible_purpose_ids must also appear in exactly one of the other two lists, or the constructor croaks. Validated via "is_vendor_allowed_for_flexible_purpose" in GDPR::IAB::TCFv2.

• check_disclosed_vendors — boolean. When true and the TC string carries a Disclosed Vendors segment, the vendor must appear there or the rule fails with "vendor N not disclosed". If the segment is absent the check is silently skipped — set the parser's strict mode at parse time if you need to require the segment's presence.

• strict — boolean. Passed through to the underlying is_vendor_*_allowed calls so invalid purpose IDs cause croak instead of a silent failure.

METHODS

validate

my $result = $validator->validate( $tc_string_or_object, %overrides );

Runs the configured rules against $tc_string_or_object. Stops at the first failing rule (fail-fast mode) and returns a GDPR::IAB::TCFv2::Validator::Result carrying that one reason.

%overrides can replace the constructor values for vendor_id, strict, and check_disclosed_vendors for this call only. The arrayref rules (consent_purpose_ids etc.) are not currently overridable per call.

$tc_string_or_object may be either a raw consent string or a pre-parsed GDPR::IAB::TCFv2 object — handy when the same TC string is being validated against multiple policies.

validate_all

Identical to "validate" but runs every rule and accumulates all failures into the result. Use when you want a complete error report rather than the first failure.

SEE ALSO

GDPR::IAB::TCFv2::Validator::Result for the result-object API, including the bool / "" overloads and the $\-aware stringification.

GDPR::IAB::TCFv2 for the underlying parser and the is_vendor_*_allowed family of methods this validator is built on.