spec-gap: trip endpoint — routeShortName sourced from route, includeReferences ignored

[Ahmedhossamdev]

Summary

Reviewing /api/where/trip/{id} against the wiki spec and the Java OBA reference
(onebusaway-application-modules) surfaced two gaps. Both were confirmed against the live
Java server (unitrans feed) and the Java source.

---

Gap 1 — entry.routeShortName is sourced from the route, not the trip

Spec

data.entry.routeShortName — Short public name for the route specific to this trip (e.g. a
variant name). May be an empty string if the trip does not carry its own route short name;
clients should fall back to the route's shortName in the references block.

Java source (the field comes from the trip, never the route)

• GenerateNarrativesTask.java:590 — builder.setRouteShortName(deduplicate(trip.getRouteShortName()))
• TripBeanServiceImpl.java:88 — tripBean.setRouteShortName(tripNarrative.getRouteShortName())
• BeanFactoryV2.java:515 — bean.setRouteShortName(trip.getRouteShortName())

trip.getRouteShortName() is the GTFS trips.txt route_short_name extension column. unitrans
and RABA do not supply it, so Java returns "" for every trip.

Live comparison

GET /api/where/trip/unitrans_A_33_outbound_0755.json
  JAVA: "routeShortName": ""
  GO:   "routeShortName": "A"

Verified across 7 unitrans routes — Java returns "" every time, while the route reference
carries the real short name.

Cause

internal/restapi/trip_handler.go set RouteShortName: route.ShortName.String, reading from the
routes table. Maglev's trips table has no route_short_name column (only trip_short_name),
so the correct, parity-accurate value is "".

Fix

Emit "" for entry.routeShortName; clients fall back to references.routes[].shortName as the
spec instructs. Test assertion at trip_handler_test.go updated accordingly.

---

Gap 2 — includeReferences=false is ignored

Spec (Extension 6a)

includeReferences=false: The references block is returned but all its sub-arrays are empty.
The route and agency are not populated.

Live comparison

GET /api/where/trip/{id}.json?includeReferences=false
  JAVA: references = { agencies:[], routes:[], stops:[], trips:[], situations:[] }
  GO:   references still fully populated with route + agency

Cause

The handler never read the includeReferences query parameter.

Fix

Parse includeReferences (default true) and only populate the references block when true.
The entry is always returned in full.

---

Notes / out of scope

• Malformed ID (no underscore): Java returns HTTP 200 + null body (a documented Java defect);
  maglev returns HTTP 400 with fieldErrors, consistent with its other endpoints. This is a
  deliberate, more-correct divergence and is left as-is.
• timeZone: "" and peakOffpeak: 0 match the Java reference and need no change.
• includeReferences handling is fixed for the trip endpoint only in this change; other endpoints
  that ignore the parameter can be addressed separately.