Policy: Add fees

[brianellin]

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

Many policies that govern mobility programs are related to fees. For example, a city may have a $0.25 per-trip fee, fees related to particular kinds of usage, or fees related to vehicle permitting.

The problem: MDS Policy currently enables agencies to communicate policy rules to providers and update those rules over time, however does not provide a way to describe fees and fees associated specific policies.

Describe the solution you'd like

A solution that's able to accurately represent real-world agency fees in the policy API. While there are many ways fees could be represented, here's an initial proposal for how it could implemented with a small number of non-breaking changes:

Additions to Rule Types

Add the following Rule Type:

fee: Fees based on regions. Rule amount refers to the fee amount in the currency defined in the Policy fee_currency.

Additions to the Rule object

Add the following new fields on Rule to support the new fee Rule Type:

• amount (Integer, optional): The amount of the fee in the currency defined in the Policy fee_currency

Additions to the Policy object

Add the following field on Policy:

• fee_currency (String, optional): An ISO 4217 Alphabetic Currency Code representing the currency of the fee, as defined in the provider/trips endpoint.

Is this a breaking change

• No, not breaking

Impacted Spec

For which spec is this feature being requested?

• policy

Describe alternatives you've considered

None at this time.

Additional context

Example uses of fee type rules:

• A city-wide trip surcharge of $.25 cents applied when a trip starts

  "name": "City Wide Trip Surcharge",
  "rule_type": "fee",
  "amount": 25,
  "geography": CITY_WIDE_GEOGRAPHY,
  "statuses": {
        "reserved": []
      }
  

• A right-of-way surcharge that is charged when a vehicle is deployed in a given area – $.25 cents downtown and $.5 cents in a historically underserved neighborhood

  "name": "Downtown Right of Way Surcharge",
  "rule_type": "fee",
  "amount": 25,
  "geography": DOWNTOWN_GEOGRAPHY,
  "statuses": {
        "available": ["service_start"]
      }
  

[marie-x]

I originally had a different design in mind, which is to put fines/fees/etc. in a separate API called Enforcement. I will do a writeup. But I think this is plausible! I think it should be informed by some policy & PolicyAPI discussions that the OMF needs to host.

[quicklywilliam]

Based on feedback from the City Services call today, we will follow up with a PR with detailed changes and additional real-world examples from fee rules in use in cities today.

[Retzoh]

Hi @quicklywilliam , were you able to make some progress on the PR that could be discussed during the city-services working group meeting ?

[quicklywilliam]

Not yet! Should have something by the next meeting though.

[Retzoh]

As discussed during the WG meeting, might have an impact on #434 regarding the units.

[quicklywilliam]

Addressed in #484

[schnuerle]

We've completed this, thanks @quicklywilliam !