Object-Action Syntax: Designing Unambiguous In-App Event Taxonomies

The Chaos of Loose Event Naming

In early-stage app development, tracking code is frequently written by multiple engineers with different mental models. One developer logs clicked_checkout_btn, another writes UserInitiatedPayment, and a third emits payment_screen_tap.

When downstream analysts attempt to construct a checkout conversion funnel, they must query three separate event names or write brittle regex aggregations. Over time, this loose syntax causes severe data debt:

Duplicate metrics across mobile releases.
Inconsistent casing (camelCase vs snake_case).
Missing contextual properties because nobody knows which properties belong to which event.

The Object-Action Grammar Defined

To establish clarity across engineering and analytics teams, Vision Spire Hub enforces the Object-Action standard. In this model, every event name consists of two parts:

The Object (Entity): The specific domain noun being acted upon (e.g., account, order, search_result, push_notification).
The Action (Verb): A past-tense verb describing the state transition (e.g., created, updated, submitted, filtered, dismissed).

[object]_[action]

Examples of Structured vs Fragile Naming

Fragile / Loose Event Name	Object-Action Standard	Rationale
`tap_like_button`	`post_liked`	Focuses on domain outcome rather than UI gesture
`submit_kyc_form`	`kyc_verification_submitted`	Identifies exact business transaction
`filter_changed`	`catalog_filter_applied`	Specifies the exact search entity affected
`user_login_success`	`user_session_authenticated`	Distinguishes authentication from raw app launch

Global Properties vs Event-Specific Attributes

A well-structured taxonomy separates Global Contextual Properties (attached automatically to every payload by middleware) from Event-Specific Properties (provided explicitly by the caller).

1. Global Context Properties (Auto-Injected)

app_build_number (Integer)
client_os_version (String)
session_id (UUIDv4)
network_carrier_type (Enum: wifi, cellular_5g, cellular_4g, offline)
device_locale (ISO-639-1 code)

2. Event-Specific Properties (Caller-Provided)

For an event like subscription_tier_selected:

tier_id (String: monthly_premium, annual_elite)
currency_code (ISO-4217: THB, USD, EUR)
pricing_amount (Decimal / Float)
discount_coupon_applied (Nullable String)

Implementing Strict Taxonomy Governance

To prevent taxonomy decay:

Maintain a Single Source of Truth: Keep event definitions in a version-controlled tracking plan rather than unmaintained wiki pages.
Compile-Time Enums: Define all event names and property keys as typed enums in Swift, Kotlin, and TypeScript.
Automate Pre-Merge Checks: Use CI schema linters to block pull requests containing unregistered event strings.