Vehicle capacity fields use units that don't fit every propulsion type (`battery_capacity` mAh, `fuel_capacity` liters)

Aperta
  • Qualcosa non va?
#993 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
3/5
Tempo stimato
1-2 giorni
Idoneità per principianti
65/100
Tipo di issue
Funzionalità
Chiarezza
Specificata chiaramente
Stato di attività
Attiva
Ambito
api, documentation

Direzione di ricerca

Review the data-types.md file to understand the current Vehicle schema and the existing capacity fields. Look at the history of the spec to see how fields have been added or deprecated. The change involves updating the specification document and possibly the JSON schema definitions. Check for any existing tests or validation scripts that might need updating. 'Done' means the spec document clearly defines the new optional fields and deprecation note, and the changes are ready for review.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Agency Provider
Is your feature request related to a problem? Please describe.

Both Vehicle capacity fields in MDS 2.x (data-types.md) have the same root problem. Each is tied to a single unit of measurement that doesn't work for every vehicle type the spec supports.

1. battery_capacity (mAh): the main problem

battery_capacity is defined as "Capacity of battery expressed as milliamp hours (mAh)".

mAh measures charge, not energy. What a battery can store (and so what range and work it can deliver) is energy: Wh = mAh × V / 1000. Without the pack's nominal voltage, an mAh value can't be compared across vehicles, and MDS has no field for voltage.

Two e-scooter packs show the problem:

Nominal voltage Charge Energy
Pack A 36 V 15 000 mAh 540 Wh
Pack B 48 V 15 000 mAh 720 Wh

The mAh values are equal, but Pack B stores a third more energy. The reverse also happens. A 400 V car pack of 200 Ah and an 800 V pack of 100 Ah both hold 80 kWh, yet by mAh the first looks twice as big.

Operators also struggle to supply the value at all. We've seen this with carshare providers: fleet and vehicle data usually give battery size in kWh. That is how vehicle makers, type-approval documents and consumer information present EV batteries (e-bike makers do the same in Wh). Converting kWh to mAh needs each model's nominal system voltage. Operators often don't have that value.

2. fuel_capacity (liters): the same problem, not yet hit in practice

fuel_capacity is defined as "Capacity of fuel tank (liquid, solid, gaseous) expressed in liters". Liters suit liquid fuels, but the spec's own propulsion types include hydrogen_fuel_cell, and combustion also covers compressed-gas fuels such as CNG. Tanks for these fuels are normally specified by mass. A hydrogen car holds about 5–6 kg, and its volume in liters depends on storage pressure. Because the field is an integer, a value in kilograms wouldn't be precise enough anyway.

We haven't received data for such vehicles yet. But MDS explicitly supports them, so the gap will appear once they're deployed in shared fleets.

Describe the solution you'd like

Two complementary, non-breaking additions, following the same pattern: a new optional field in the unit that suits the vehicle, alongside the existing one.

In the next 2.x minor release (non-breaking):

Field Type Required/Optional Description
battery_energy_capacity (new) Integer Required if Available Energy capacity of the battery at nominal voltage, expressed in watt-hours (Wh)
fuel_capacity_mass (new) Integer Required if Available Capacity of fuel tank for fuels measured by mass (e.g. hydrogen, CNG), expressed in grams (g)
battery_capacity Integer Required if Available Deprecated in favor of battery_energy_capacity
fuel_capacity Integer Required if Available Unchanged, clarified as: Capacity of fuel tank for liquid fuels, expressed in liters

In 3.0 (breaking):

  • Remove battery_capacity (mAh).
  • fuel_capacity stays for liquid fuels.

Integer Wh keeps enough precision for small micromobility packs (e.g. 540) and has room for car packs (e.g. 77000). Integer grams stores hydrogen tank sizes accurately (e.g. 5600).

Is this a breaking change
  • No, not breaking for the 2.x part: it adds two optional fields, deprecates one, and clarifies wording.
  • Removing battery_capacity in 3.0 is breaking, and belongs in that major release.
Impacted Spec

For which spec is this feature being requested?

  • agency
  • provider
Describe alternatives you've considered
  1. Change the unit of battery_capacity to Wh in place. This is simpler, but it changes the meaning of an existing field. It could only happen in 3.0, and until then data from different providers would be ambiguous.
  2. Add an optional battery_voltage field (nominal V) so consumers can derive Wh from mAh. This asks providers for a value that is harder to get than Wh, and it still leaves the useful quantity to be derived.
  3. Add a unit field (e.g. fuel_capacity_unit: liters | kg, default liters). It's non-breaking in the schema, but clients are expected to ignore fields they don't recognize. An existing consumer would therefore silently read a hydrogen car's fuel_capacity in kg as liters, which is the same ambiguity described above. It also doesn't fix the integer precision problem for kilograms.
  4. Keep the current units and clarify the text. This doesn't fix comparability and doesn't help providers who only have kWh.
Additional context
  • Both capacity fields first appeared in 2.0.0 with the multi-modal expansion. We couldn't find any earlier discussion of the choice of units.
  • #643 (trip energy consumption) already treated battery capacity in Wh as the natural input for energy calculations.

I will be happy to open a PR against dev or any other branch once there's agreement on the direction.

Lingua principale
Nessun dato sulla lingua
Stelle
753
Fork
255
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di openmobilityfoundation/mobility-data-specification

Tutte le issue di openmobilityfoundation/mobility-data-specification

Issue simili

Altre issue su Backend & API Design

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.