🐛📄 – Improve event_type naming convention in passenger_events

[chrisyamas]

Problem Description

The current TIDES spec uses event types as strings with spaces (e.g., "Passenger boarded") in the passenger_events table. This naming convention creates practical challenges when working with the data, particularly in:

• Column naming for unpivot operations
• Variable naming in code and queries
• General data manipulation tasks

Current Specification

The passenger_events table includes event types such as:

• "Passenger boarded"
• "Passenger alighted"
• "Vehicle arrived at stop"
• "Ramp deployed"
• "Kneel deployed"

These string values with spaces cannot be directly used as column names or variable names in most programming languages and database systems without modification.

WMATA's Implementation Experience

During WMATA's implementation:

• Internal event types are represented as numeric codes (e.g., event_type values 3 and 5)
• Conversion between internal codes and TIDES string values requires additional mapping logic
• Analytical operations that involve pivoting or unpivoting data by event type become more complex
• Variable naming in code requires additional transformation of the event type strings

While this issue is relatively minor compared to other implementation challenges, it creates unnecessary friction in working with TIDES data.

Possible Solution

We propose changing the event type naming convention to use underscore-delimited strings instead of spaces:

Current Format	Proposed Format
"Passenger boarded"	"passenger_boarded"
"Passenger alighted"	"passenger_alighted"
"Vehicle arrived at stop"	"vehicle_arrived_at_stop"
"Ramp deployed"	"ramp_deployed"
"Kneel deployed"	"kneel_deployed"

This change would maintain human readability while significantly improving technical usability.

Alternative Approaches

Option 1: Provide Both Code and Description

Another approach would be to follow the pattern used in other TIDES enumerations, providing both a code and a description:

{
  "event_type_code": "passenger_boarded",
  "event_type_description": "Passenger boarded"
}

Option 2: Maintain Current Format with Implementation Guidance

If changing the specification is not desirable, provide implementation guidance on how to handle spaces in event types for common operations:

When using event types in column names or variable names, implementers should replace spaces with underscores and convert to lowercase.

Impact

Adopting underscore-delimited strings would:

1. Improve usability in database operations (pivoting, unpivoting, filtering)
2. Simplify code that references event types
3. Reduce the need for string manipulation in implementations
4. Align with common naming conventions in data engineering

Backward Compatibility

This change would require updates to existing implementations, but the transformation is straightforward:

• Replace spaces with underscores
• Optionally convert to lowercase

A transition period could be established where both formats are accepted to minimize disruption.

Additional Considerations

While this issue was marked as lower priority in WMATA's implementation discussions, addressing it would improve the developer experience and reduce friction in working with TIDES data. The change is relatively simple but would have a positive impact on all implementations.

[jaygordon]

I agree with what seemed to be the consesus (or majority view) on today's Contributors Group call: that something both human- and machine-readable like passenger_boarded is what should be used in TIDES format. Implementers might choose to handle these internally by those strings or by integer index, and to present them in UIs or other formatted output with their own human-friendly labels (like "Passenger boarded," with capitalization depending on use case and the implementer's convention) so I don't see a need to build the human-friendly version into the spec as in Option 1.