📄🚀 – Modify passenger_events table to accommodate fare gate and station-based events

[chrisyamas]

Issue Summary

This proposal addresses a gap in the TIDES specification with regard to handling fare gate events and other station-based passenger movements that are not directly associated with vehicles. The table schemas in the current spec lack a clear mechanism to store passenger events that occur at fixed locations like fare gates, particularly when operating in "free mode" without fare transactions, or when tracking non-interactive ridership during normal operations.

Identified Need

Transit agencies operating rail systems and other fixed-infrastructure transit modes need to track passenger movements through fare gates and station entry/exit points. The current TIDES specification presents challenges for these use cases:

• The fare_transactions table is designed for monetary transactions, not passenger movement events without associated fares
• The passenger_events table requires a vehicle_id, which doesn't apply to station-based events
• The station_activities table is too aggregated for event-level data needed for operational analysis

Addressable Audience

This change would benefit:

• Large rail transit agencies (ex. WMATA, MTA New York, BART, etc.) with fare gate infrastructure
• Bus rapid transit systems with off-board fare collection and platform validators
• Multi-modal agencies needing unified passenger event tracking across vehicle and station contexts
• Agencies operating in special circumstances such as free-fare periods, emergencies, or special events where gates operate without fare validation
• Analytics teams requiring granular passenger flow data for capacity planning and operational optimization

Proposed Solution

Based on extensive discussion with WMATA analytics personnel and the TIDES Contributors Group, we propose the following modifications to the passenger_events table to create a more flexible and comprehensive approach to passenger event tracking.

1. Make device_id Required Instead of vehicle_id

Current Specification:

• vehicle_id is required
• device_id is optional

Proposed Change:

• Make device_id required
• Make vehicle_id optional with constraint exception: "required unless the event occurs at a fixed location (station/stop)"

Rationale: This change allows the passenger_events table to accommodate both vehicle-based and station-based events. For station-based events like fare gate entries and exits, the device_id would identify the specific fare gate, while vehicle_id would be null. This flexibility enables agencies to capture passenger events from a wider variety of collection methods (including handheld validators, camera-based equipment, or other technology) while maintaining data integrity.

2. Make Trip Attributes Optional

Current Specification:

• trip_stop_sequence is required

Proposed Change:

• Make trip_stop_sequence optional with constraint exception: "required unless the event is not associated with a trip"

Rationale: Station-based fare gate events are not associated with specific trips, so requiring trip_stop_sequence forces implementers to use placeholder values. Making this field optional for station-based events improves data quality and reduces confusion.

3. Add Optional Foreign Key to Linked Fare Transaction

Current Specification:

• No direct link between passenger events and fare transactions

Proposed Change:

• Add an optional linked_transaction_id field that references transaction_id in the fare_transactions table

Rationale: This allows agencies to link passenger movements with their associated fare transactions when applicable, enabling more comprehensive analysis of passenger flows and fare collection. For events in "free mode" or other non-fare situations, this field would be null.

4. Simplify Event Types

Current Specification: The event_type field includes values like:

• "Passenger boarded"
• "Passenger alighted"

Proposed Change: Simplify to two universal event types:

• "Passenger entry" (for any device recording someone entering)
• "Passenger exit" (for any device recording someone exiting)

Rationale: Based on Contributors Group feedback, the distinction between station vs. vehicle events is already captured in the devices table through device_type. This simplification reduces complexity while maintaining the ability to distinguish context through the device information.

Implementation Considerations

Backward Compatibility

The proposed changes are designed to maintain backward compatibility:

• Existing vehicle-based passenger events would continue to work as before
• New optional fields would only be used by agencies that need them
• Constraint exceptions allow flexible use without breaking existing implementations

Data Validation Updates

With these changes, data quality checks would need updating to:

• Validate that either vehicle_id or device_id is provided (but not necessarily both)
• Check that trip_stop_sequence is provided when the event is associated with a trip
• Validate that linked_transaction_id references a valid transaction when provided

Relationship to Device Types

The existing devices table with its device_id and device_type fields provides sufficient context to distinguish between fare gate events and onboard vehicle events, eliminating the need for complex event type proliferation.

Future Considerations

The following related items were identified during discussion but should be addressed as separate proposals:

1. Device Status Table: Creation of a new table to track device maintenance activities and offline status
2. Non-Passenger Vehicle Events: Potential relocation of vehicle equipment operations (ramp deployment, kneeling) from passenger_events to vehicle_locations
3. Hardened Conditional Requirements: Future refinement of conditional requirements based on specific device types

Next Steps for Issue Working Group

Per the [TIDES Change Management Process](https://tides-transit.org/main/governance/policies/change-management), the Issue Working Group assigned to this issue should:

1. Review and refine the proposed schema changes
2. Update the schema and documentation according to the proposal on a feature branch
3. Submit a pull request to the develop branch

References

• Original fare gate events discussion: [GitHub Issue #228 ]
• [TIDES Change Management Policy](https://tides-transit.org/main/governance/policies/change-management)
• Notes: September TIDES Contributors Group discussion of the proposal

---

This proposal represents a normative content change to the TIDES specification. Implementation should follow the established change management process, including review by the Issue Working Group and eventual integration into the main specification.

[mpaine-act]

Should this go under a station_events table instead as any fare gate and station-based events cannot assume the event is caused by a passenger (e.g. police, janitor, station staff, etc.)?