NAME

GDPR::IAB::TCFv2 - TCF v2.3 distribution: parser, validator, CMP-validator, and CLI

PROJECT STATUS

GDPR::IAB::TCFv2 entered maintenance mode on 2026-05-15 with the v0.512 release. The core parser, validator, and CMP-validator surfaces are considered feature-complete for the IAB TCF v2.3 specification.

In maintenance mode the maintainer commits to bug fixes, security fixes, CPAN-tester regression triage, and tracking IAB-spec updates (TCF v2.4 / v3 if and when they ship). Larger feature work -- the remaining roadmap phases (GVL-aware validator, Special Features / Special Purposes, CLI configuration loading), the distribution items (DockerHub automation, Debian package), and the sister-distribution ideas in "ECOSYSTEM" -- is now tracked as help-wanted issues on GitHub.

Patches and PRs from the community are welcome and will continue to be reviewed. See TODO at the repository root for the full help-wanted list and CONTRIBUTING for the patching workflow.

SYNOPSIS

This module is the documentation hub for the GDPR-IAB-TCFv2 distribution. It exposes a thin Parse delegate that returns an instance of GDPR::IAB::TCFv2::Parser:

use feature qw<say>;
use GDPR::IAB::TCFv2;

my $consent = GDPR::IAB::TCFv2->Parse(
    'CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA.argAC0gAAAAAAAAAAAA'
);

say $consent->cmp_id;             # 21
say $consent->consent_language;   # 'EN'
say $consent->is_v23 ? 'v2.3' : 'older';

For declarative compliance checks, see GDPR::IAB::TCFv2::Validator. For one-liner / shell-use shortcuts, see "ONE-LINER USAGE" below.

COMPONENTS

The distribution ships several pieces. Each link below jumps to the relevant module or section.

GDPR::IAB::TCFv2::Parser

The bit-stream parser. Parse returns an instance whose accessors, predicates, and JSON serializer answer every question about a TC string.

GDPR::IAB::TCFv2::Validator

Declarative compliance checks. $validator->validate($tc_string) asserts a vendor's presence in the string for a given purpose set on a given legal basis.

GDPR::IAB::TCFv2::CMPValidator

Validates that a TC string's cmp_id is registered in the IAB's public CMP list (file, JSON, or URL-loaded snapshot).

iabtcfv2 (Perl module)

A pure-exporter short alias for one-liner and shell use. Provides tcf($s) and validator(%opts) as importable functions. See "ONE-LINER USAGE".

bin/iabtcfv2 (CLI)

Subcommand-style command-line utility. iabtcfv2 dump emits parsed JSON; iabtcfv2 validate runs declarative compliance checks against a vendor identity and a purpose set. See "COMMAND LINE TOOLS".

Docker image

Pre-built Docker Hub image peczenyj/gdpr-iab-tcfv2 wraps the CLI for portable use. See "DOCKER USAGE".

INCOMPATIBLE CHANGES

v0.500

The parser implementation moved from GDPR::IAB::TCFv2 to a new subpackage GDPR::IAB::TCFv2::Parser. The class-method delegate remains: GDPR::IAB::TCFv2->Parse(...) still works and is the recommended entry point. However, the returned object is now blessed into GDPR::IAB::TCFv2::Parser rather than GDPR::IAB::TCFv2:

my $c = GDPR::IAB::TCFv2->Parse($s);

# Before v0.500:
ref($c) eq 'GDPR::IAB::TCFv2'             # true
$c->isa('GDPR::IAB::TCFv2')               # true

# v0.500 and later:
ref($c) eq 'GDPR::IAB::TCFv2::Parser'     # true
$c->isa('GDPR::IAB::TCFv2::Parser')       # true
$c->isa('GDPR::IAB::TCFv2')               # false

Every method call, every JSON output byte, and every CLI behavior is unchanged. The break only affects code that asserts the exact class name via ref, isa, blessed, Storable::thaw, or similar.

CONSTRUCTOR

Parse

GDPR::IAB::TCFv2->Parse($tc_string, %opts) is the entry point for parsing TCF v2.3 consent strings. It delegates to GDPR::IAB::TCFv2::Parser->Parse and returns a GDPR::IAB::TCFv2::Parser object; see that page for the full constructor contract (strict, prefetch, json options).

COMMAND LINE TOOLS

This distribution includes a unified command line tool to work with TC strings.

iabtcfv2

The iabtcfv2 utility provides several subcommands for TCF v2.3 strings.

dump

Parses TC strings and output them as JSON.

# Basic usage
iabtcfv2 dump "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Pretty printed JSON
iabtcfv2 dump --pretty "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Stream multiple strings from STDIN as JSON Lines
cat strings.txt | iabtcfv2 dump

# Pipe through `jq -s` if you need a single JSON array
cat strings.txt | iabtcfv2 dump | jq -s .

# Short flags can be bundled (the last bundled short may take a value)
iabtcfv2 dump -pi "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"
iabtcfv2 dump -pv 284 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Long options accept the GNU `--opt=value` form
iabtcfv2 dump --vendor-id=284 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

validate

Validates TC strings against a vendor identity and a set of declared purpose lists, emitting one JSON record per string (or text lines with --text). The vendor must be allowed for every purpose in --consent-purposes on a consent basis, and for every purpose in --legitimate-interest-purposes on a legitimate-interest basis. Exit code is 0 when every string is valid, 1 on any parse or validation failure, 2 on bad CLI usage.

# Basic usage: vendor must appear in the TC string
iabtcfv2 validate -v 284 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Require vendor 284 to be allowed for purposes 1 and 3 on consent basis
iabtcfv2 validate -v 284 -C 1,3 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Require both consent (purposes 1, 3) and legitimate interest (purpose 7)
iabtcfv2 validate -v 284 -C 1,3 -L 7 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Accumulate every failing rule (validate_all) instead of fail-fast
iabtcfv2 validate -av 284 -C 1,3 -L 7 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Human-readable text output instead of JSON
iabtcfv2 validate -tv 284 -C 1,3 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Reject TC strings whose policy version is below 5 (TCF v2.3)
iabtcfv2 validate -v 284 -m 5 "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

# Pipeline-friendly: -q suppresses output, only the exit code is meaningful
if iabtcfv2 validate -qv 284 -C 1,3 "$tc_string"; then
    echo "ok"
fi

# Stream multiple strings from STDIN as JSON Lines (pipe through
# `jq -s` if you need a single JSON array)
cat strings.txt | iabtcfv2 validate -v 284 -C 1,3

See iabtcfv2 --help or perldoc iabtcfv2 for more details.

For script-free invocation without bin/iabtcfv2, see "ONE-LINER USAGE".

ONE-LINER USAGE

The distribution supports perl -M... one-liners directly. The iabtcfv2 module exports tcf($s) (which returns a GDPR::IAB::TCFv2::Parser) and validator(%opts) (which returns a GDPR::IAB::TCFv2::Validator), making short scripts even shorter.

Print one field

perl -Miabtcfv2 -E 'say tcf(shift)->cmp_id' "$tc"

Equivalent long form (no shortcut module):

perl -MGDPR::IAB::TCFv2 -E 'say GDPR::IAB::TCFv2->Parse(shift)->cmp_id' "$tc"

Multi-field TSV

perl -Miabtcfv2 -E '
    my $c = tcf(shift);
    say join("\t", $c->cmp_id, $c->cmp_version, $c->consent_language,
                   $c->vendor_list_version, $c->policy_version)
' "$tc"

Emulate `iabtcfv2 dump --pretty` via core JSON::PP

perl -Miabtcfv2 -MJSON::PP -E '
    say JSON::PP->new->convert_blessed->canonical->pretty
                ->encode(tcf(shift))
' "$tc"

Stream multiple strings on STDIN

perl -Miabtcfv2 -nE '
    chomp;
    my $c = eval { tcf($_) } or next;
    say join("\t", $_, $c->cmp_id)
' < strings.txt

Validate

perl -Miabtcfv2 -E '
    my $r = validator(vendor_id => 284, consent_purpose_ids => [1,3])
            ->validate(shift);
    say $r ? "ok" : "fail: $r"
' "$tc"

DOCKER USAGE

This tool is also available as a Docker image on Docker Hub.

Basic Usage

docker run --rm peczenyj/gdpr-iab-tcfv2 dump "CLcVDxRMWfGmWAVAHCENAXCkAKDAADnAABRgA5mdfCKZuYJez-NQm0TBMYA4oCAAGQYIAAAAAAEAIAEgAA"

Processing Streams (STDIN)

To process a stream of strings via pipe:

cat strings.txt | docker run -i --rm peczenyj/gdpr-iab-tcfv2 dump

To type strings manually:

docker run -it --rm peczenyj/gdpr-iab-tcfv2 dump

ACRONYMS

GDPR: General Data Protection Regulation

IAB: Interactive Advertising Bureau

TCF: The Transparency & Consent Framework

FUNCTIONS

looksLikeIsConsentVersion2

Will check if a given tc string starts with a literal C.

ECOSYSTEM

The following sister distributions are intentionally left as help-wanted ideas rather than shipped from this module. Each one is companion glue for a popular Perl framework and would add a runtime dependency on its host framework, so they belong as separate CPAN distributions rather than features of GDPR::IAB::TCFv2 itself.

• GDPR::IAB::TCFv2::Validator::LIVR

  LIVR rule-engine binding for JSON-shaped TC string payloads.

• GDPR::IAB::TCFv2::Validator::TypeTiny

  Reusable Type::Tiny constraints (parameterized by purpose / vendor sets) for Moo, Moose, or pure-Perl callers that prefer type-level enforcement.

• Plack::Middleware::GDPR::TCFv2

  Plack middleware that decodes a TC string from a request header or cookie, attaches a parsed GDPR::IAB::TCFv2 object to $env, and short-circuits the response when consent is missing or invalid.

• GDPR::IAB::TCFv2::Validator::Moose

  Moose attribute traits and role-based validation for Moose-end-to-end projects.

• GDPR::IAB::TCFv2::Validator::FormValidator

  Data::FormValidator profile glue for legacy applications that drive business validation through DFV.

The help-wanted issues on GitHub track each of these ideas; see https://github.com/peczenyj/GDPR-IAB-TCFv2/issues?q=label%3Aecosystem and TODO for context.

SEE ALSO

GDPR::IAB::TCFv2::Parser for the parser API.

GDPR::IAB::TCFv2::Validator for declarative compliance checks.

GDPR::IAB::TCFv2::CMPValidator for CMP-list validation.

iabtcfv2 for one-liner / shell-use shortcuts.

The original IAB documentation of TCF v2.

AUTHOR

Tiago Peczenyj mailto:tiago.peczenyj+cpan@gmail.com

THANKS

Special thanks to ikegami for the patience on several question about Perl on Stack Overflow.

BUGS

Please report any bugs or feature requests to https://github.com/peczenyj/GDPR-IAB-TCFv2/issues.

LICENSE AND COPYRIGHT

Copyright 2023-2026 Tiago Peczenyj

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

DISCLAIMER

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.