Skip to content

Conditional Filters

A conditional filter changes its scope or output based on the data it encounters — not on fixed structural conditions like object type or category.

Where a basic filter asks "is this a door?", a conditional filter asks "does this object have the parameter I need?" or "is this family editable?".

When conditional filters are appropriate

Use a conditional filter when:

  • The rule only applies to elements that carry a specific parameter
  • The rule must exclude families that cannot be edited
  • The filter output should include a field only when it exists on the object
  • Two different element types need to be handled differently in one rule

Do not use conditional filters when a simple structural condition is enough. Complexity should be earned.

The most common patterns

Scope based on parameter existence

$[type = "FamilySymbol" and $exists(values.p_8fe8f5ce)]

Restricts the rule to elements where the parameter key is present. Elements without the key are outside scope — not errors.

Scope based on editability

$[type = "Family" and values.isEditable = true]

Excludes system families and read-only content before touching type or instance data.

Conditional output field

{
  "id": id,
  "fireRating": $exists(values.fireRating) ? values.fireRating : null
}

Returns the field only when it exists, instead of letting JSONata return undefined.

The risk: hiding real problems

The most common mistake with conditional filters is accidentally excluding elements that should be reported.

/* Wrong — elements without the parameter are silently excluded */
$[type = "FamilyInstance" and values.mark != null]

If the filter condition involves the value being validated, bad data never reaches the validator. The rule always passes — silently.

Conditional filters define scope. They never fix data.

Use with care

Conditional filters:

  • increase cognitive load
  • are harder to debug than structural filters
  • should always be explained in the rule description

When a rule uses conditional logic, make the intent explicit in comments or the rule name. A reader should immediately understand why the condition exists.