[chrisyamas]

Summary

Adds new vehicle_crew table to support multiple crew members per vehicle/trip, including mid-trip reliefs. This addresses the limitation where trips_performed.operator_id could only reference a single operator.

Resolves #220

Changes

• spec/vehicle_crew.schema.json (new) defines the vehicle_crew table with:
  • Primary key: [service_date, trip_id_performed, crew_id, start_time]
  • Required fields: service_date, vehicle_id, crew_id, start_time
  • Optional fields: trip_id_performed (for vehicle-level assignments), crew_role, end_time
  • crew_role enum: operator, conductor, fare_inspector, other (uses snake_case consistent with 🐛📄 – Improve event_type naming convention in passenger_events #235)
  • Foreign references to trips_performed, vehicles, and operators
• samples/template/TIDES/vehicle_crew.csv (new) provides header-only template
• spec/trips_performed.schema.json updated operator_id description to clarify optional usage and reference to vehicle_crew table for multi-operator scenarios
• spec/tides-datapackage-profile.json added vehicle_crew to tides-table enum
• samples/template/TIDES/datapackage.json added vehicle_crew resource entry
• CHANGELOG.md added entries under [Unreleased] for new table and description change

Reason for this change

Rail systems commonly have multiple crew members (operators, conductors) on a single trip, and operator reliefs mid-trip are standard practice. The current trips_performed.operator_id field can only reference one operator, forcing agencies to either lose crew data or pick an arbitrary operator to record.

The new vehicle_crew table allows agencies to capture complete crew assignment history while keeping the existing operator_id field for simple single-operator cases.

- See related discussion in Issue #220 and Fall 2025 TIDES Issues Working Group notes from December 1 and December 10.

Review checklist

Per change management policy, the following must be met before feature branch changes can merge to develop branch:

• All JSON files validate
• Reviewed and approved by 2+ contributors or board members

---

Community review status (updated September 2, 2026)

How community review works: Per the TIDES Change Management Policy, a proposal moves forward once at least three TIDES Contributors outside the originating working group publicly comment with a score: Accepted, Accepted with minor changes, or Substantially revised. A few sentences with your read of the proposal is a complete review.

Originating working group (Fall 2025 Issues Working Group, December 1 and 10, 2025 sessions): Christopher Yamas, Gabriel Sánchez Martínez, Ian Thistle, Jay Gordon, John Levin, Joey Reid, Spenser Sutinen. Their work is reflected in the proposal itself; community review comes from Contributors beyond this group.

Review so far: Laurie Merrell (@laurie-jarvus) and @jabhij have posted scored reviews (Accepted; Accepted with minor changes, with clarifications answered in the thread). One more review from a Contributor outside the working group completes community review.

Community review remains open, and reviews are welcome while we finalize v2.0. If you have not yet weighed in, a short comment closing with where you land (Accepted / Accepted with minor changes / Substantially revised) is all we need.

The full v2.0 map lives on #271.

[github-actions]

Documentation available at: http://tides-transit.github.io/TIDES/feature/issue-220-vehicle-crew

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	⚠️

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	⚠️

[chrisyamas]

Data Validation Report

Sample Status
./samples/template/TIDES ⚠️

This warning is because the frictionless validation check can't find the vehicle_crew.schema.json since it checks against main branch and the schema for the new table doesn't exist on main branch yet. But this should resolve automatically once the PR is merged.

[botanize]

I believe this meets the needs discussed in the issue. However, it looks like this PR accidentally removes trip_id_performed from the trips_performed table. I also suspect that trip_id_performed should be required if it's part of the primary key. Though to be fair, it doesn't strictly need to be, service_date, crew_id and start_time should be sufficient for the primary key. Including trip_id_performed just makes it easier to use.

• undo removal of trips_performed.trip_id_performed

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	⚠️

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	⚠️

[chrisyamas]

Heads up @jlstpaul @botanize @jaygordon @laurie-jarvus @jabhij @wtimmerman-fitp @mpaine-act that this proposal has been revised again in response to the review here, so it's re-circulating per the change management policy (at least 72 hours, previous reviewers notified).

With this round of changes, the vehicle_crew primary key is now [service_date, vehicle_id, crew_id, start_time], anchored on the vehicle rather than the trip, and trip_id_performed is optional (usually populated, but a single assignment can span consecutive trips). These changes have followed Joey's point about interlining, Abhishek's question about the grain of the table, and John's identification of the value of keeping the trip reference available for easy joins. The crew table from the previous round remains unchanged.

If nothing here gives you pause, it will proceed, and fresh reviews are welcome either way. We still need one more scored review from outside the original working group on this one.

[mpaine-act]

The vehicle-anchored key appropriately supports continuous crew assignments across interlined trips and mid-trip reliefs, with an optional trip reference where applicable. I support the broader crew terminology, including contractors, and the proposed crew_role values.

Before finalizing, please:

• Clarify role precedence and effective-date matching between crew and vehicle_crew

  • Example: A person’s crew record says operator, but their vehicle_crew assignment says conductor, but which wins? If that person has several dated crew records, which one should the assignment use?

• Document assignment interval boundaries and overlap rules.

  • If one operator’s assignment ends at 10:00 and another’s starts at 10:00, is only the incoming operator assigned at that instant? Making the end time exclusive removes ambiguity. For overlaps, two crew members on the same vehicle can be valid (an operator and conductor). and having the same person assigned to two different vehicles at overlapping times generally indicates an error. The spec should distinguish these cases.

• Please also register vehicle_crew in tides.spec.json and update the remaining “Operators” title.

Accepted with minor changes.

[github-actions]

Data Validation Report

Sample	Status
./samples/template/TIDES	⚠️

[jlstpaul]

• Clarify role precedence and effective-date matching between crew and vehicle_crew
• Document assignment interval boundaries and overlap rules.
• Please also register vehicle_crew in tides.spec.json and update the remaining “Operators” title.

@mpaine-act Please review changes in f46d182 and 746135a

[lauriemerrell]

It was mentioned on a call yesterday that my review was requested -- I have not fully tracked the changes here and defer to the existing reviewers, please let me know if I'm specifically needed for quorum and I can review more carefully? But I don't have any concerns and don't intend to be a blocker.

[botanize]

I think the enums for crew_role are too limited and I'm not sure if they should be expanded or just free text fields.

[botanize]

Not sure it's worth making this an enum. I can already think of a couple additional roles that really shouldn't be grouped into other, e.g., "police", "trainer", "supervisor"

[botanize]

Same here, either expand the enum options or make this a string.

[jlstpaul]

I think the enums for crew_role are too limited and I'm not sure if they should be expanded or just free text fields.

I agree that we should expand the list of roles. I don't think it is necessary to do this immediately, as I think it would be better to do this over time, informed by implementation experience. In particular, while there are a lot of roles within an agency, we should consider more carefully which are ones that agencies want to capture in connection with the operational data contained in TIDES

I would not make this just a text field. There is a lot of consistency within the industry on the types of crew roles. I think it is reasonable to agree on the pre-defined list, and I think this approach provides greater clarity to users of the data about what those values mean.

f we find the need for more freeform role details, I would rather add an additional descriptive text field in the future. For example, while most agencies have the role of a vehicle operator (driver), the different types of operators vary greatly within and across agencies. If an agency wants to captures the type of operator, that should be a secondary text field.

My biggest remaining concern is that we have two crew_role fields, on crew and vehicle_crew, that need to stay coordinated. In particular, the values of vehicle_crew.crew_role should be a subset of crew.crew_role. But the two tables will not necessarily always have the same list of enumerated values, so they still need to be managed separately.

[jaygordon]

I'm assigned as a reviewer but I missed several conversations, so if my suggestions have already been discussed and resolved please disregard.

1. @gabriel-korbato summarized the group's reason for choosing "crew" over "employee," which I agree with except that a crew is a group of people and the crew table is a table of individuals. Did we already consider crew_members? To me that's much more precise, though obviously longer, but the length would be offset by my next point.
2. vehicle_crew is a group of people working together, which to me is the definition of a crew. So my instinct would be to call this crew.

Taking both points together, we'd have a crew table that references a vehicle, a time range, and one or more crew_members.

[chrisyamas]

Thanks @botanize for taking a look, and @jlstpaul for the thoughtful answer. I think John's approach makes sense for alpha.1: keep crew_role as a defined list for now, and grow it from what agencies actually need to capture alongside their operational data, with a separate descriptive field later if people need more detail than the list gives them. I've opened #288 to expand the crew_role values from implementation experience, starting with your three examples (police, trainer, supervisor), so they don't get lost. Wondering if that would be enough for you to clear your review from Sept 10?

[chrisyamas]

Thanks @jaygordon, that's a really good point, and you're right that a crew is the group rather than the individual. I think the rename is worth taking up, but renaming both tables is a bigger change than this revision round, and the current names came out of the group discussion Gabriel summarized back in August. So for alpha.1 I'd like to keep crew and vehicle_crew as they are, and I've opened #289 so crew_members and crew can be considered before v2.0 beta or final. Would that work for you?

[chrisyamas]

Just wanted to give a heads up to @laurie-jarvus @botanize @wtimmerman-fitp @jaygordon @mpaine-act @jabhij that this proposal has been revised again, this time in response to Michael Paine's review (thank you Michael!), so it's re-circulating per the change management policy (at least 72 hours, previous reviewers notified).

With this round of changes, John has worked the clarifications Michael asked for into the spec text. When vehicle_crew.crew_role is populated it takes precedence over crew.crew_role, and when it's empty, the role on the crew record effective on the service_date applies. A crew member has one effective crew record at a time, and crew.end_date is now exclusive. Assignment start_time is inclusive and end_time is exclusive, so at a handoff only the incoming crew member is assigned at that instant. Multiple crew members on the same vehicle at the same time is valid (an operator and a conductor, for example), while the same person assigned to two vehicles at overlapping times indicates an error. vehicle_crew is also now registered in tides.spec.json, and the leftover "Operators" title is now "Crew". The crew_role values stay as they are for alpha.1, with expanding them from implementation experience tracked in #288, and vehicle_crew.crew_role now says its values are a subset of crew.crew_role's. (Abhishek's earlier points on the crew_id referent, vehicle and trip consistency, and temporal semantics were addressed in the previous rounds)

The table names stay as they are for alpha.1, and Jay's suggestion to rename them (crew_members and crew) is tracked in #289 to revisit before v2.0 beta or final.

If nothing here gives you pause, it will go ahead and proceed through review in accordance with the CMP, and fresh reviews are welcome either way. @botanize thanks for the approval! The only changes since then are the wording fixes listed above and the subset line, so a fresh approval on the new head whenever you have a moment would be great, and @laurie-jarvus no need for a deep dive given your comment, but if a fresh approval on the new head works for you, it would definitely help. Thank you all!