🐛📄 – Rename 'duration' fields in stop_visits for clarity

[chrisyamas]

Problem Description

In the TIDES stop_visits table, several fields representing durations use the suffix _time instead of a more appropriate suffix like _duration or _seconds. This inconsistent naming creates confusion because other fields ending with _time in TIDES tables represent timestamps, not durations.

The specific fields in question are:

• ramp_deployed_time
• kneel_deployed_time
• lift_deployed_time

Current Specification

The current TIDES specification includes these fields in the stop_visits table with the _time suffix, despite them representing durations rather than timestamps. This creates a naming inconsistency within the TIDES schema that could lead to implementation errors or misinterpretation of the data.

WMATA's Implementation Experience

In WMATA's implementation:

• These fields are currently set to NULL in the dbt models
• While not actively using these fields yet, the naming inconsistency was identified as a potential source of confusion as implementation progresses
• The inconsistency was flagged during schema review as a potential issue for future data users

Proposed Solution

We propose renaming these fields to use a more appropriate suffix that clearly indicates they represent durations:

Current Field Name	Proposed Field Name
ramp_deployed_time	ramp_deployed_duration
kneel_deployed_time	kneel_deployed_duration
lift_deployed_time	lift_deployed_duration

Alternatively, the suffix _seconds could be used if the values specifically represent seconds:

Current Field Name	Alternative Proposed Name
ramp_deployed_time	ramp_deployed_seconds
kneel_deployed_time	kneel_deployed_seconds
lift_deployed_time	lift_deployed_seconds

Impact

Renaming these fields would:

1. Improve clarity and consistency in the TIDES schema
2. Reduce the likelihood of implementation errors
3. Make the purpose of these fields more immediately apparent to data users
4. Align with best practices for naming duration fields

Backward Compatibility

This change would require updates to existing implementations, but since:

1. The change is straightforward
2. These fields may not be widely used yet (they are NULL in WMATA's implementation)
3. The semantic meaning of the fields is not changing

The impact on existing implementations should be minimal.

Additional Considerations

While this issue was marked as lower priority in WMATA's implementation discussions, addressing it now would prevent potential confusion as more agencies implement TIDES and begin using these fields. The change is simple but would improve the overall quality and consistency of the TIDES specification.

[botanize]

I think seconds is the right unit, and doing something like defining a duration type around ISO-8601 Durations is overkill.

Despite the slight potential to confuse duration fields as something like ISO-8601 Duration, I think ramp_deployed_duration might be slightly preferable to ramp_deployed_seconds, though to be honest I often use something like ramp_deployed_s in my own work. With a clearly documented spec I don't think the exact name is critical.

[jlstpaul]

I also tend to favor _duration, but I am not opposed to _seconds.

[jaygordon]

I'm fine with duration or seconds.

Seconds is nice because it documents the units right there in the field name. Duration is nice because it can reduce ambiguity about whether the field conveys, for example, the duration of a ramp deployment rather than the time elapsed between the the start of the stop visit and the start of the ramp deployment. (I'd probably assume the former interpretation but others may differ.)

I'm also fine with abbreviating these if it's clear enough, so _duration, _dur, _seconds, or _sec.

[botanize]

Last minute idea, _dur_s, e.g., lift_deployed_dur_s?

[mpaine-act]

To keep the data self-documenting, names of fields or tabular column names should not be abbreviated.