Propagation policies

When you save privacy preferences through the Consent API (v3), you can apply a propagation policy to automatically extend a user's consent choice across related privacy notices. This page explains how notice hierarchies work and describes each available policy.

Notice hierarchies

Privacy notices in Fides can be organized into parent-child hierarchies. A parent notice represents a broad data-use category, while child notices represent more specific uses within that category.

For example:

Marketing (parent)
├── Email marketing (child)
├── SMS marketing (child)
└── Targeted advertising (child)

These hierarchies let you group related notices so that consent choices can be managed at different levels of specificity. Without a propagation policy, each notice in the hierarchy is independent -- a user would need to submit a separate preference for every notice in the tree.

What propagation policies do

A propagation policy defines rules for how a consent choice on one notice flows to related notices in the same hierarchy. When a policy is active and a user submits a preference, Fides automatically generates additional preferences for parent or child notices based on the policy's rules.

These policy-generated preferences are stored alongside the user's explicit choices and are distinguishable through their per-preference metadata. When a preference is generated by a propagation policy, Fides sets the following fields in the preference's meta.fides object:

This gives you a complete audit trail: for any policy-generated preference, you can trace it back to the exact user choice and policy that created it.

Available policies

Fides provides five propagation policies. The table below summarizes the direction each policy propagates choices:

cascade_down_opt_out

This is the default policy when no policy parameter is specified.

When a user opts out of a parent notice, that opt-out is applied to all descendant notices. Opt-in choices are not cascaded -- only opt-outs flow downward. Nothing propagates upward to parent notices.

Best for: Ensuring that opting out of a category opts the user out of everything beneath it, without letting a parent opt-in override individual child choices.

cascade_down_all

Any choice (opt-in, opt-out, or acknowledge) on a notice is applied to all descendant notices. Nothing flows upward.

Best for: Scenarios where a parent choice should be authoritative for everything underneath it.

cascade_up_all

Child choices roll up to ancestor notices. For a parent's value to be derived from its children, all children must agree. If children have conflicting values, the request is rejected.

Best for: Cases where a parent should reflect the unanimous choice of its children. For example, if a user opts out of every child notice, the parent also shows as opted out.

cascade_up_all_cascade_down_all

Combines both directions: explicit choices cascade down to all descendants, and child choices roll up to ancestors using the same unanimity rule as cascade_up_all. Setting one child does not force unrelated siblings to change.

Best for: Full parent-child consistency without unexpected side effects on sibling notices.

cascade_down_all_cascade_up_opt_in_all_opt_out_conservative

Explicit choices cascade down to all descendants. Choices also cascade upward with separate rules for opt-in and opt-out:

• Opt-in cascades up aggressively: if any child is opted in, the parent is opted in.
• Opt-out cascades up conservatively: the parent is only opted out when all children (including previously saved and default preferences) are opted out.

If a child opts out but other children remain opted in, the parent stays unchanged.

Best for: Scenarios where opt-in should take priority at the parent level. The parent only shows as opted out when everything beneath it is opted out.

Specifying a policy

Pass the policy query parameter when calling the save preferences endpoint:

curl -X POST 'http://localhost:8080/api/v3/privacy-preferences?policy=cascade_down_all' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identity": {
      "email": { "value": "user@example.com" }
    },
    "preferences": [
      {
        "notice_key": "marketing",
        "notice_history_id": "pri_notice-history-abc-123",
        "value": "opt_out"
      }
    ]
  }'

In this example, using cascade_down_all, the opt-out for the "marketing" notice is automatically applied to all of its descendant notices (such as "email_marketing" and "sms_marketing").