Coding tips for writing rules

Coding tips for writing rules

In this article, you will learn about the coding tips for writing rules.

Before you begin

To learn why rules are important in SPAN sports performance analysis platform, refer to this article.

Coding tips for writing rules

The coding tips for rules in SPAN are shown below.



Once you start using rules in SPAN, the next step is learning how to write them correctly. The good part is - you don't need to be a coder to do this. Rules in SPAN follow a simple structure. Think of them as a way of telling the system: "If something looks incorrect, flag it."

Below are some essential coding tips that will help you write clean, effective, and easy-to-maintain rules.

1. Use "any" when any condition can match (OR)

Use "any" when you want to flag an event if even one condition is true. This is the most common use case in SPAN.

For example, if you want to catch:
  • incorrect duration
  • OR wrong timing
  • OR unusual tag count

Even one issue is enough → use "any"
Simple thinking: "If anything looks wrong, flag it."

2. Use "all" when all conditions must match (AND)

Use "all" when multiple conditions together define a situation.

For example, checking if duration is within a range:
  • duration ≥ 0.1
  • AND duration ≤ 5

Both must be true → use "all"
Simple thinking: "All conditions together define the rule."

3. Keep "event.type" always "flagged"

In SPAN, rules are mainly used to detect issues.
So it's best to keep: event.type = "flagged"
This keeps your workflow simple and consistent. Every time something looks incorrect, the system flags it. No confusion, no multiple action types.

4. Write clear "event.params.reason" messages

This is one of the most important tips. Whenever a rule flags an event, the user will see the reason.

So make sure it is:

  • simple
  • clear
  • user-friendly

Good examples:

  • "Invalid event time: startTime is greater than endTime"
  • "Event duration is too short"
  • "Unexpected number of tags"

Avoid vague messages like "Error detected".

Goal: The reviewer should instantly understand what went wrong.

5. Use numeric "operators" correctly

These are used when working with numbers like duration, time, or counts.

Here are the main ones:

  • lessThan → fact < value
  • lessThanInclusive → fact ≤ value
  • greaterThan → fact > value
  • greaterThanInclusive → fact ≥ value

These are useful when:

  • defining ranges
  • setting limits
  • validating time or duration

Example thinking:
"Duration should not be less than 0.1"
"Start time should not be greater than end time"

6. Use string / array "operators" properly

These are useful when working with labels, categories, or lists.

Common ones include:

  • equal → exact match
  • notEqual → not equal
  • in → matches one of multiple values
  • notIn → does not match any of them
  • contains → value exists in a list
  • doesNotContain → value does not exist in a list

These are especially useful for validating:

  • labels
  • categories
  • tagging patterns

Example thinking:
"Labels should not contain 'serve_error'"
"Primary category should be one of these values"

7. Understand the available "facts"

Facts are simply the event data you can check.

In SPAN, the most commonly used facts are:

Time-related

  • startTime → when the event starts
  • endTime → when the event ends
  • duration → how long the event is

Tag-related

  • tagCount → number of tags
  • labelCount → number of labels
  • labels → list of labels

Category-related

  • primaryCategory → main category
  • secondaryCategories → additional categories

You don’t need to use all of them - just pick what is relevant to your workflow.

How to think while writing rules

Instead of starting with JSON, start with a simple thought: "What mistake do I want to catch?"

Then convert it:

  • What data to check → fact
  • What condition → operator
  • What is wrong → value

That’s all a rule is.

Final thought

Writing rules in SPAN is not about coding - it's about clarity. You are simply defining what "incorrect" looks like in your workflow and letting the system check it automatically. Start with a few simple rules. As you observe patterns, keep improving them.

Over time, these small checks will:

  • reduce manual effort
  • improve consistency
  • and significantly improve data quality

And that's what makes rules such a powerful feature in SPAN.

    • Related Articles

    • Why rules?

      When tagging scales or even when it doesn't - Quality can drift In the early stages of a tagging workflow, things feel controlled. Whether it's a single analyst or a small team, the logic is clear and the volume is manageable. But over time - as more ...

    • Access rules page

      In this article, you will learn how to access the Rules page of a template. Before you begin To learn how to create and open a template in SPAN sports performance analysis platform, refer to this article. Access rules page After opening the template ...

    • Save rules for a template

      In this article, you will learn how to save rules for a template. Before you begin To learn how to access the Rules page and view some rule examples for a template in SPAN sports performance analysis platform, refer to this article. Save rules for a ...

    • Multiple rules for a template

      In this article, you will learn how to write multiple rules for a template. Before you begin To learn how to access the Rules page and view some rule examples for a template in SPAN sports performance analysis platform, refer to this article. ...

    • Use multiple rules with all (AND logic across rules)

      In this article, you will find the rules document for using multiple rules with all (AND logic across rules). Before you begin To learn how to access the rules page, refer to this article. Use multiple rules with all (AND logic across rules) Note: ...