> ## Documentation Index
> Fetch the complete documentation index at: https://docs.solya.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Tagging rules — scope & propagation

> Restrict which entities a rule evaluates, and control how a tag propagates through the hierarchy.

A rule's optional `scope` decides **which entities** it evaluates and **how the tag
propagates**.

```json theme={null}
"scope": {
  "entityType": "VARIANT",
  "propagationMode": "BUBBLE_UP",
  "brandIds": ["<uuid>"],
  "productIds": [],
  "taxonomies": [ { "type": "gender", "values": ["M"] } ],
  "collections": ["<uuid>"]
}
```

## Scope fields

| Field             | Meaning                                                                                   |
| ----------------- | ----------------------------------------------------------------------------------------- |
| `entityType`      | The entity the rule targets: `PRODUCT`, `BRAND`, `VARIANT`, `INVENTORY_ITEM`. Always set. |
| `brandIds`        | Restrict to these brands.                                                                 |
| `productIds`      | Restrict to these products.                                                               |
| `taxonomies`      | Restrict by dimension — each `{ type, values }` (e.g. gender = M).                        |
| `collections`     | Restrict to these collections.                                                            |
| `propagationMode` | How the tag spreads through the hierarchy (below).                                        |

An empty/absent filter means "no restriction on that dimension". Filters combine to narrow
the evaluated population.

## Propagation modes

The hierarchy is **Brand → Product → Variant → Inventory item**.

| Mode           | Effect                                                                          |
| -------------- | ------------------------------------------------------------------------------- |
| `ENTITY_ONLY`  | Tag only the matched entity (default — no propagation).                         |
| `CASCADE_DOWN` | Also tag the entity's descendants (e.g. brand → its products → their variants). |
| `BUBBLE_UP`    | Also tag the entity's ancestors (e.g. variant → its product → its brand).       |

Entity hierarchy and propagation modes:

```mermaid theme={null}
graph TD
  B["Brand"]
  P1["Product"]
  V1["Variant"]
  I1["Inventory Item"]
  P2["Product"]
  V2["Variant"]
  I2["Inventory Item"]
  
  B -->|CASCADE_DOWN| P1
  P1 -->|CASCADE_DOWN| V1
  V1 -->|CASCADE_DOWN| I1
  B -->|CASCADE_DOWN| P2
  P2 -->|CASCADE_DOWN| V2
  V2 -->|CASCADE_DOWN| I2
  
  I1 -->|BUBBLE_UP| V1
  V1 -->|BUBBLE_UP| P1
  P1 -->|BUBBLE_UP| B
  
  V1 -.->|ENTITY_ONLY| V1
```

<Note>
  The exact propagation traversal runs in the data platform's tag-evaluation engine; the
  rule only declares the mode. Choose `CASCADE_DOWN` to label a whole sub-tree from a
  higher level, or `BUBBLE_UP` to mark a parent because one of its children matched.
</Note>