Skip to main content

Expressions

Scorecards uses an intuitive, JSON path-like syntax to define both entity selection and validation rules. This powerful expression system allows you to create precise, targeted validations for your Backstage entities.

Understanding Expressions​

Expressions in Scorecards serve two main purposes:

  • Selecting which entities a rule applies to, and
  • Defining validation criteria for those entities.
info

All expressions use a consistent syntax based on JSON path, making them easy to learn and maintain.

Selector Expressions​

Selectors determine the scope of your rules using a simple, clear syntax:

$kind is <EntityType>

For example:

  • $kind is Component targets all component entities
  • $kind is API targets all API entities

Available Operators​

Scorecards provides a rich set of operators for building expressions:

Comparison operators​

  • == - Equality comparison
  • != - Inequality comparison
  • > - Greater than
  • < - Less than
  • >= - Greater than or equal
  • <= - Less than or equal
  • is - Case-insensitive string equality
  • ~ - Regular expression match

Logical operators​

  • and - Logical AND
  • or - Logical OR
  • not - Logical NOT

Access operators​

  • . - Property access (e.g., $metadata.name)
  • @ - Array index access

Arithmetic operators​

  • + - Addition
  • - - Subtraction
  • * - Multiplication
  • / - Division
info

Operators follow a precedence order (highest to lowest):

  1. Access (., @)
  2. Arithmetic (*, /, +, -)
  3. Comparison (>, <, >=, <=)
  4. Equality (==, !=, is, ~)
  5. Logical (and, or)

Field References​

Scorecards provides several special fields for accessing entity data:

  • $entity - Access the entire entity object.

  • $kind - Access the entity kind.

    $kind is Component

  • $metadata - Access core entity information.

    $metadata.name      # Entity name
    $metadata.owner     # Entity owner

  • $namespace - Access the entity namespace.

    $namespace == "default"

  • $spec - Reference entity specifications.

    $spec.type         # Entity type
    $spec.lifecycle    # Lifecycle stage
    $spec.definition   # API definition

  • $annotations - Access integration metadata.

    $annotations."gitlab.com/instance"      # GitLab instance
    $annotations."gitlab.com/project-slug"  # GitLab project
    $annotations."jira/project-key"         # Jira project

Rule Examples​

Here are examples from the pre-configured golden rules:

  • API Validation

    $metadata.name and $spec.type and $spec.lifecycle and $spec.owner and $spec.definition

  • Component Validation

    $metadata.name and $spec.type and $spec.lifecycle and $spec.owner

  • GitLab Integration

    $annotations."gitlab.com/instance" and $annotations."gitlab.com/project-slug"

  • Jira Integration

    $annotations."jira/project-key"
info

Rules use the and operator to combine multiple criteria. All conditions must be true for validation to pass.

Best Practices​

Follow these guidelines for effective rule creation:

  • Clear selectors: Use specific entity types to target the right components.

  • Focused validation: Keep each validation criteria focused on a single aspect.

  • Consistent paths: Use standard annotation paths across related rules.

  • Logical grouping: Group related validations together for better organization.

  • Documentation: Add clear descriptions for complex validation rules.

  • Operator precedence: Be aware of operator precedence and use parentheses when needed.

  • Field access: Use the most specific field accessor for your needs.