Filtering with inclusion lists — scalable category filtering

Note

This example introduces the use of JSONata variables. Variables improve readability and scalability, but should only be used once basic filtering is understood.

When a rule applies to multiple categories, using repeated or conditions quickly becomes messy and error-prone.

The recommended approach is to use an inclusion list.

(
  /* Category inclusion */
  $CategoryInclusion := ["OST_Doors", "OST_Windows"];

  $[
    type = "FamilySymbol"
    and values.category.label in $CategoryInclusion
  ].{
    "id": id,
    "type": type,
    "name": name,
    "assemblyCode": values.assemblyCode
  }
)

---

What is new in this filter

1. Defining a list

$CategoryInclusion := ["OST_Doors", "OST_Windows"];

This creates a list (array) containing allowed categories.

Key points:

• Square brackets [...] define a list
• Values must match exactly (case-sensitive)
• Trailing commas are allowed here but discouraged for clarity

This list represents:

“These are the categories this rule applies to.”

---

2. Using a variable

The $ prefix indicates a JSONata variable.

$CategoryInclusion

Variables:

• Are scoped to this expression
• Improve readability
• Prevent copy-paste mistakes
• Make rules easier to maintain

Instead of repeating values, you define them once.

---

3. The in operator

values.category.label in $CategoryInclusion

This means:

“Check whether the category label exists in the inclusion list.”

This replaces multiple or conditions and is functionally equivalent to:

values.category.label = "OST_Doors"
or values.category.label = "OST_Windows"

But it is:

• Clearer
• Safer
• Easier to extend

---

Why this approach is preferred

Readability

You immediately see:

• Which categories are included
• What the rule scope is

Maintainability

To add another category:

$CategoryInclusion := ["OST_Doors", "OST_Windows", "OST_CurtainWallPanels"];

No logic changes required.

Consistency

The same pattern can be reused across many rules, which:

• Reduces bugs
• Improves review speed
• Makes rules easier to standardise

---

Important rules when using inclusion lists

• Always use API category labels (OST_*)
• Never mix UI names and API labels
• Keep inclusion lists at the top of the expression
• Use clear variable names (CategoryInclusion, not $list1)

---

Common mistakes to avoid

Forgetting the $ when referencing the variable

values.category.label in CategoryInclusion

❌ Invalid — variable not found.

---

Putting logic inside the list

["OST_Doors" or "OST_Windows"]

❌ Wrong — lists contain values, not logic.

---

Filtering values inside the list instead of the data

$CategoryInclusion in values.category.label

❌ Reversed logic — will never work.

---

Rule of thumb

If you find yourself repeating or, you should probably be using a list.