[Policy API] support parking fees by duration

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

Some cities have implemented fees where the rate varies by how long the vehicle is parked. This is to encourage operators to move vehicles.

Describe the solution you'd like

Proposals for extending MDS Policy API -

• add new field for rate_duration, similar to what's in CurbLR for payments
• allow for arrays in rate_amount and rate_duration so we don't have to create new rules to accommodate the different rates by duration

Is this a breaking change

No? Because this concept doesn't currently exist in Policy so this would be additive.

Impacted Spec

For which spec is this feature being requested?

• policy

Describe alternatives you've considered

No other viable alternatives.

Additional context

See Omaha's permit, Exhibit B

[marie-x]

I think this can be implemented with Policy as-is via multiple Rules. I will read the details and confirm.
Thanks for the link to the document! Is super useful.

@Karcass suggested a possible solution in #632 but after speaking with my engineers they don't think it's very clear that this is a duration based policy. I would prefer to include rate_duration instead of trying to bend the current fields. Using the current fields in a way that they weren't intended requires a lot of familiarity with the Policy API to understand.

[quicklywilliam]

Not sure whether it is better to respond here or in #632 but like @Karcass I think this may be possible without changes to Policy via some improved documentation. This could be done by documenting how the minimum/maximum properties can be used with rate. Alternatively, we could clarify that time can be a rate specified, as @Karcass suggests.

That's not to say that Rates can't or shouldn't be changed (it's a beta for a reason after all), but I'm wary of adding new fields without addressing existing ambiguity and open-endedness in the spec. My hope is that we can discover changes that will both clarify and simplify the Policy specification.

[marie-x]

Here's an example provided by @avatarneil, showing a Policy for escalating rates of the form:

• $2 for the first hour
• $4 for the second hour
• $10 for every after after that

{
  "name": "Tiered Dwell Time Example",
  "description": "First hour $2, second hour $4, every hour onwards $10",
  "policy_id": "2800cd0a-7827-4110-9713-b9e5bf29e9a1",
  "start_date": 1558389669540,
  "publish_date": 1558389669540,
  "end_date": null,
  "prev_policies": null,
  "provider_ids": [],
  "rate_recurrence": "each_time_unit",
  "currency": "USD",
  "rules": [
    {
      "name": "> 2 hours",
      "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9",
      "rule_type": "time",
      "rule_units": "hours",
      "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
      "statuses": { "available": [], "non_operational": [] },
      "vehicle_types": ["bicycle", "scooter"],
      "maximum": 2,
      "rate_amount": 1000
    },
    {
      "name": "1-2 Hours",
      "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2",
      "rule_type": "time",
      "rule_units": "hours",
      "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
      "statuses": { "available": [], "non_operational": [] },
      "vehicle_types": ["bicycle", "scooter"],
      "maximum": 1,
      "rate_amount": 400
    },
    {
      "name": "0-1 Hour",
      "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54",
      "rule_type": "time",
      "rule_units": "hours",
      "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
      "statuses": { "available": [], "non_operational": [] },
      "vehicle_types": ["bicycle", "scooter"],
      "maximum": 0,
      "rate_amount": 200
    }
  ]
}

[jiffyclub]

Let's say we have a vehicle parked for 4.5 hours. My understanding of "First hour $2, second hour $4, every hour onwards $10" is that that would be charged 2 + 4 + 3 * 10 = $36? For code that wants to evaluate this policy, hour 4 is in violation of all of these rules, but only the "> 2" should be used in the fee calculation. How do you imagine that code decides which rule to apply, assuming that only one does? (What about a situation where it's ok for more than one rule to apply? Is it implied that only one rule can apply at a time and multiple policies need to be used to apply multiple rules to the same event?)

[jrheard]

Great questions!

How do you imagine that code decides which rule to apply, assuming that only one does?

Policy rules have a "short-circuiting" behavior that makes it so that the first matching rule is the only rule in the policy that applies. (That language is tucked away at the end of the readme and is pretty easy to miss IMO, although I have no useful suggestions for how to improve that situation 🙂 )

(What about a situation where it's ok for more than one rule to apply? Is it implied that only one rule can apply at a time and multiple policies need to be used to apply multiple rules to the same event?)

My personal interpretation of the spec leads me to believe that you're correct, and that multiple policies need to be used to apply multiple rules to the same event.

[jiffyclub]

So it sounds like the way to implement this would be to take the parked duration, go through the rule list, hit the first one and say "a portion of this parked duration violates this rule, I'm going to calculate that fee and then remove the matching portion of the parked duration to create a new, shorter parked duration", then repeat that process until you run out of parked duration or make it through the rule list without matching one.

I'm sure there are multiple ways to do it, but that's what came to mind.

[quicklywilliam]

Here's an example provided by @avatarneil, showing a Policy for escalating rates of the form:

• $2 for the first hour
• $4 for the second hour
• $10 for every after after that

{
  "name": "Tiered Dwell Time Example",
  "description": "First hour $2, second hour $4, every hour onwards $10",
  "policy_id": "2800cd0a-7827-4110-9713-b9e5bf29e9a1",
  "start_date": 1558389669540,
  "publish_date": 1558389669540,
  "end_date": null,
  "prev_policies": null,
  "provider_ids": [],
  "rate_recurrence": "each_time_unit",
  "currency": "USD",
  "rules": [
    {
      "name": "> 2 hours",
      "rule_id": "9cd1768c-ab9e-484c-93f8-72a7078aa7b9",
      "rule_type": "time",
      "rule_units": "hours",
      "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
      "statuses": { "available": [], "non_operational": [] },
      "vehicle_types": ["bicycle", "scooter"],
      "maximum": 2,

Is this supposed to be minimum: 2?

  "rate_amount": 1000
},
{
  "name": "1-2 Hours",
  "rule_id": "edd6a195-bb30-4eb5-a2cc-44e5a18798a2",
  "rule_type": "time",
  "rule_units": "hours",
  "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
  "statuses": { "available": [], "non_operational": [] },
  "vehicle_types": ["bicycle", "scooter"],
  "maximum": 1,
  "rate_amount": 400
},
{
  "name": "0-1 Hour",
  "rule_id": "6b6fe61b-dbe5-4367-8e35-84fb14d23c54",
  "rule_type": "time",
  "rule_units": "hours",
  "geographies": ["0c77c813-bece-4e8a-84fd-f99af777d198"],
  "statuses": { "available": [], "non_operational": [] },
  "vehicle_types": ["bicycle", "scooter"],
  "maximum": 0,
  "rate_amount": 200
}

]
}

[schnuerle]

Could someone please start a pull request for this (and some of the other related issues that needs Policy examples) and add the relevant examples and stand alone file discussed so far to the Policy Examples page? Suggesting @marie-x @quicklywilliam @jiffyclub @avatarneil or anyone else who can.

[avatarneil]

@quicklywilliam I think that it should be maximum, at least the way I was thinking about this. During evaluation, it'd be identified that the rule specifies a maximum of 2 hours for 'time', and if a vehicle had been parked for >2h that'd trigger a 'violation' of the rule (short-circuiting evaluation for the subsequent rules). If it was encoded as minimum, then the vehicle would not be in violation of the rule, rather, it'd be permitted because it has been there for over 2 hours.

@schnuerle I'll keep you in the loop about if I have time to make a proper PR for this; we're currently wrapping up our planning cycle for Q3 work so I'm still a little fuzzy on how much bandwidth I'll have, but if I have time I'd be happy to write up a PR for this. Are we hoping to include this in the 1.2 cycle?