vehicle_capacity and vehicle_type_capacity

[josee-sabourin]

After reviewing the specification, MobilityData has realized the differentiation between vehicle_capacity and vehicle_type_capacity is not extremely clear. This is due, in part, to both the geofencing.json and vehicle_types.json extensions occurring concurrently. As a result, both of these fields were not able to be viewed in tandem before being merged into the specification.

vehicle_capacity is defined as:

An object where each key is a vehicle_type_id as described in vehicle_types.json and the value is a number representing the total number of vehicles of this type that can park within the area defined in the station_area field. If the field station_area is defined and a particular vehicle type id is not defined in this object, then an unlimited virtual capacity is assumed for that vehicle type.

vehicle_type_capacity is defined as:

An object where each key is a vehicle_type_id as described in vehicle_types.json and the value is a number representing the total docking points installed at this station, both available and unavailable for the specified vehicle type.

Given that v2.1 is still in RC, we feel these fields should be clarified before an official release. What would be the best way to do that?

• Renaming vehicle_capacity? (ex: station_area_capacity, vehicle_type_area_capacity, vehicle_type_virtual_capacity, etc.)
• Renaming vehicle_type_capacity? (ex: vehicle_type_dock_capacity, or others)
• Editing the descriptions to make them more clear?
• All of the the above?
• Other solutions?

Please let us know what you think and if you're implementing these fields!

[kanagy]

+1 Good catch, it is really not clear that vehicle_capacity relates to station_area. We're not implementing these fields, but I think renaming this to station_area_capacity or similar would make it a lot clearer. The description reads fine.

[mplsmitch]

Since both of these refer to available parking space, as opposed to the capacity of vehicles, I suggest renaming to parking_capacity and vehicle_type_parking_capacity.

[josee-sabourin]

How important is it that "vehicle_type" be included in the names of the fields themselves? Is it sufficient for it to be mentioned in the description of the field? Adding vehicle type may make things lengthy.
Example:
station_area_capacity vs. vehicle_type_station_area_capacity
station_area_parking_capacity vs. vehicle_type_station_area_parking_capacity
dock_capacity vs. vehicle_type_dock_capacity

Additionally, the fields themselves should ideally clarify that vehicle_capacity pertains to station_area and virtual stations, whereas vehicle_type_capacity refers to docked stations.

[barbeau]

My votes are for vehicle_type_area_capacity and vehicle_type_dock_capacity (both in station_information.json), for the following reasons:

• Keeping the prefix vehicle_type helps differentiate between these two fields (which are specific to vehicle_types) and the pre-existing field capacity (which is for all vehicle docking points, not separated by type), which is in the same file
• area should be sufficient instead of the longer station_area, given that these fields are in station_information.json

I'd also vote to re-order the docs to put all 3 capacity-related fields adjacent to one another to avoid scrolling to read the different definitions.

[davidlewis-ito]

Without wanting to further complicate things... I note that in the station_status.json, the current dock availability allows the description of docks that can support multiple vehicle types (ie vehicle_docks_available is an array of an array of vehicle_type_ids).

It seems therefore that the descriptions in station_status and station_information have rather diverged. So an example:

3 types of vehicle: V1, V2, V3.
2 types of physical dock: D1 (supports V1 and V2) and D2 (V3 only).
An example station is equipped with 10 x D1 and 5 x D2

In the current proposal this seems to be represented as:

station_information:
"capacity": 15,
"vehicle_type_dock_capacity": {
"V1": 10,
"V2": 10,
"V3": 5,
}

station_status
(say with 8 x D1 free and 4 x D2 free)
"num_docks_available": 12,
"vehicle_docks_available": [{
"vehicle_type_ids": ["V1","V2"],
"count": 8
}, {
"vehicle_type_ids": ["V3"],
"count": 4
}],

Two questions : i) are we happy with this difference ? ii) should we align any name changes such that perhaps "vehicle_docks_available" becomes "vehicle_type_dock_available" ?

[mplsmitch]

Closing this out - This issue is captured in PR #269 which is currently open for vote until 11:59PM UTC on October 13th, 2020. Please get on over there and vote.