Canonical Categories

Signal defines a fixed, CMP-agnostic vocabulary for consent purposes. Customers map their CMP’s category codes (Cookiebot’s statistics, OneTrust’s C0002, custom codes, etc.) onto this vocabulary once in Settings → Consent, and every vendor blueprint can then reference consent without knowing anything about the customer’s CMP.

The vocabulary

How it appears on events

Every event the SDK emits carries both views:

{
  "context": {
    "consent": {
      "categories": {
        "necessary": true,
        "preferences": true,
        "statistics": false,
        "marketing": false
      },
      "canonical": {
        "essential": true,
        "functional": true,
        "analytics": false,
        "marketing": false
      }
    }
  }
}

• categories is keyed by your CMP’s codes verbatim — useful for audit, custom blueprints, and when you intentionally want CMP-specific behaviour.
• canonical is keyed by the vocabulary above — the recommended source for vendor blueprints.

If no categories in your provider have a canonical classification, canonical is omitted entirely and only categories is emitted. This is the back-compat shape — older blueprints that reference context.consent.categories.marketing keep working.

Referencing canonical from a blueprint

# GA4 — works for any CMP once the customer maps their categories
- target: "@root.consent.ad_user_data"
  source: "context.consent.canonical.marketing"
  transform:
    type: value_map
    map:
      "true": GRANTED
      "false": DENIED
 
- target: "@root.consent.ad_personalization"
  source: "context.consent.canonical.marketing"
  transform:
    type: value_map
    map:
      "true": GRANTED
      "false": DENIED

# Meta CAPI — gate PII fields on canonical.marketing
- target: "user_data.em"
  source: "user.email_sha256"
  condition:
    field: "context.consent.canonical.marketing"
    equals: true

Classifying CMP categories

When you add a consent provider in Settings → Consent, each category row has a Canonical Category dropdown:

• Pick the canonical bucket that best matches the category’s purpose.
• For known CMPs (Cookiebot, OneTrust) Signal pre-fills the standard mapping — adjust only if your deployment differs.
• Leave the dropdown blank for categories you don’t want surfaced canonically (they still appear under categories so custom blueprints can read them).

Mapping examples

Cookiebot (auto-seeded)

OneTrust (auto-seeded)

Custom CMP with split marketing

canonical.marketing becomes true if either ads_targeting or social_marketing is granted. The OR-merge matches “user gave consent for this purpose somewhere.”

Migration notes

From legacy consent shape

Earlier versions of the SDK emitted a flat context.consent shape:

{ "context": { "consent": { "analytics": true, "marketing": false } } }

Current SDK builds emit the nested categories + canonical shape. Blueprints that referenced the old flat path should migrate to the canonical path:

From CMP-specific blueprints

Older blueprints that hardcoded a CMP’s vocabulary (e.g. context.consent.categories.statistics for Cookiebot) should switch to context.consent.canonical.<purpose>. Once the customer classifies their categories, the blueprint becomes portable across CMPs.

Roll-out order

When upgrading from CMP-specific to canonical refs:

1. Deploy the SDK first — categories and canonical are emitted side-by-side, so old and new blueprints both work.
2. Classify categories in Settings → Consent — until categories are classified, canonical is empty and canonical-aware blueprints will see all-false.
3. Bump the blueprint version — switch source paths to context.consent.canonical.* and ship as a new revision.
4. Upgrade attached integrations — pipelines pin to a specific revision; update each pipeline’s integration to the new revision when ready.

Related

• Consent overview — CMP integration, enforcement, audit logging.
• Identity — canonical consent gates vendor identifier syncs.