Supporting units of time with varying durations

[zanebclark]

@michael-danko-passport brought up a good point around the discussion of #72. What is a month, quarter, or year? All three of these units of time differ in duration from one unit to the next. How do we address this on the backend? It seems as though there's value in allowing for such a unit of time. @HenryEspinosa talked about selling permits on the basis of a month. His organization would also need to define the word month at the time of sale. Is it a "rolling" month (e.g. from the 17th of one month to the 17th of the next month), a calendar month, or something else entirely?

Proposals (not mutually exclusive):

1. We could do away with month and support rolling_month and calendar_month. For rolling_month, the start of the month-long period would be determined by the Policy time_span.start_date or the smallest value in the days_of_month array (or require a single day of month in the days_of_month array). For calendar_month, we could use only the month of the Policy time_span.start_date or the first month to occur in the months array (or require a single month in the months array). This gets a bit complex.
2. When a Rate is defined as minute or hour, it's pretty clear that we expect this rate to start and stop automatically as specific user_classes park. In the case of @HenryEspinosa's permit example, there is a pre-arranged party with a pre-arranged timeframe and a pre-arranged rate that (correct me if I'm wrong, @HenryEspinosa) is expressed as a lump sum. We could introduce a rate_unit enum that is intended to reflect a lump sum. For example, fixed. The rate for the permit (in this example) would be expressed as a lump sum and would expire per the terms of the Policy time_span

[zanebclark]

@schnuerle brought up a good point: How are we handling this in MDS? Is there an analogous use case that we could learn from? Or, as @schnuerle hinted at, is this a problem that is unique to curb usage?

[schnuerle]

Looking at MDS now, it's not exactly the same situation. Eg. there isn't a 'month' unit defined.

Here is where Rules start: https://github.com/openmobilityfoundation/mobility-data-specification/tree/main/policy#rules

There are enumerated days of the week, and start/end for a time of day. Then there are rule_units which can include time units like seconds, minutes, hours, and days, but that's it so far, no weeks or months.

So MDS may not be analogous to what's happening here in CDS yet.

[schnuerle]

I added a new field here called "rate_unit_period". I think this can get at the solution. Let me know your thoughts. I feel like I may be missing something though.

https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/curbs/README.md#rate

[zanebclark]

I started a few threads below. I'm not a huge fan of the new field. If rate_unit needs rate_unit_period, rate_unit isn't meaningful. If rate_unit doesn't need rate_unit_period, rate_unit_period isn't meaningful. That suggests that we're splitting one concept up over two fields.

[schnuerle]

I don't think putting rolling_* and calendar_* for a few new enums makes sense, like rolling_month and calendar_month, rolling_quarter and calendar_quarter, rolling_year and calendar_year, etc.

Adding a new field that is optional with a default value seems to work better in this case.

[zanebclark]

Your comment below convinced me that there's value in both fields across the board

[zanebclark]

I think some clarification in the documentation is still in order. Potentially an example. Otherwise, great addition, @schnuerle !

[zanebclark]

Would rate_unit_period clarify rate_unit values of quarter and year as well?

[schnuerle]

Yes I think it would.

[zanebclark]

If rate_unit is second, minute, hour, day, or week, what would rate_unit_period represent? If I understand the purpose of the field, It feels like it wouldn't have any meaning for these rate_unit values.

[schnuerle]

Maybe no meaning, but maybe it could? Eg 1 hour parking means from the moment of parking plus an hour, so actually that's rolling.

It does mean though that "calendar", "rolling" might not make sense, since "calendar" seems to be at the month level or higher. Need another word like "full_unit" or something.

And maybe "rolling" is the default then?

[zanebclark]

🤔 Good point. Would "calendar" hour be from the 0th minute to the 60th minute? If you were to park there on minute 49, you would pay for that hour? This concept is very similar to increment_minutes, but in the case of increment_minutes: 60, you would pay from minute 49 to minute 1:49. In the case of a rate_unit_period: calendar, rate_unit: hour, you would pay for minute 0 to minute 60.

And maybe "rolling" is the default then?

I think so

[zanebclark]

or is it rolling based on a time from within the rate_unit

I would spell out exactly what fields from rate_unit would be used to interpret the beginning and end of the period.

[schnuerle]

I've got a new pass at this solution that I feel good about. Please review today if you can, especially @zanebclark.

https://github.com/openmobilityfoundation/curb-data-specification/blob/release-1.0.0/curbs/README.md#rate

It clarifies how rate_unit_period works, and provides a link to an example in code. Please review example too.

I had added some language about how 'calendar' only typically works for units a week or larger, but really they can work for smaller units. Like in the example I created, it can apply to all day parking, where you pay a flat fee for the day regardless of when you start parking that day. Same could happen with an hour time slot, eg, you pay for only from when you start to the start of the next hour to allow turn over or reservations maybe.

Note too that even though 'calendar' the word isn't exactly right for units an hour or less since they are less than a calendar day, I think the term still applies and I could not find a more generic term that applies to all time units.

[zanebclark]

@schnuerle , I left some thoughts

[jlarsonOmahaNE]

@schnuerle I like how this flows. I do have one question/concern, would this be able to incorporate an extension of your parking? Say you park for 2 hours but can now add on another 2 hours after that.

[schnuerle]

I think the policy defines the rates per hour, and if you start a parking session, then add more time, I think that would either extend your current session or start a new session. But either way I think calculating this is outside of the scope of Curbs now - Curbs just says what the rules are, but how long you stay or billing for that is not in Curbs. That can be handled in Events though I think, leaving the definition of a session up to the capabilities of the data source operator and sensors.

[jlarsonOmahaNE]

Thank for the info, that makes sense to me.

[zanebclark]

An addendum to @schnuerle 's answer: @jlarsonOmahaNE , you could use increment_amount:

{
  "rate": 1,
  "rate_unit": "hour",
  "rate_unit_period": "rolling",
  "increment_amount": 2
}

[zanebclark]

When you went over your 2 hours, you would automatically be paying for 2 more hours

[schnuerle]

Here is the latest conversations about this inline with the code:

89109ff

And where the latest changes are for you all to review in the large description for rate_unit_period :

https://github.com/openmobilityfoundation/curb-data-specification/tree/release-1.0.0/curbs#rate