Expression Best Practices

Keep Expressions Small

• one or two comparisons are fine
• long boolean chains should become a Java condition token
• repeated expressions should become named static conditions
• expressions should read safe views only
• avoid service calls, IO, mutation, and infrastructure access

Prefer Static Conditions For Domain Logic

Use static conditions when the check has business meaning, needs validation, or will be reused:

{
  "type": "LEVEL_AT_LEAST",
  "params": {
    "level": 10
  }
}

Use expressions when the check is a short combination of already exposed data:

{
  "type": "expr",
  "expr": "player.level() >= 10 && player.hasPermission('vip')"
}

Use when For Action-Specific Checks

Use an action when guard when the rule should match once but only some actions need an extra expression check. Do not duplicate the whole rule just to guard one action.

Protect The Expression Surface

• keep expression security enabled for external rule files
• expose ExpressionAccessible views instead of mutable domain objects
• add scalar values with putScalar
• do not expose services, repositories, classloaders, file APIs, or reflection
• keep project-owned security policies named by trust level

Performance

• cache expression views for objects used in hot paths
• prefer static Java conditions for frequently fired complex checks
• keep trigger indexes specific so expression rules are not evaluated for unrelated events
• use RuleDocumentFormat.SPECIAL for large metadata rule files with expressions