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

オープン
  • 何か問題がありますか？
#993 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

まだ誰も着手していません。

評価

難易度
3/5
見積もり時間
1〜2日
初心者へのやさしさ
65/100
issue の種類
機能追加
明瞭さ
明確に書かれている
活発さ
活発
領域
api, documentation

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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.

主要言語
言語のデータがありません
スター
753
フォーク
255
30日以内にマージされた PR はありません

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

openmobilityfoundation/mobility-data-specification のほかの issue

openmobilityfoundation/mobility-data-specification の issue をすべて見る

似ている issue

Backend & API Design の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。