Policy: add "rates" (fees + subsidies)

policy/README.md

@@ -30,6 +30,7 @@ The goal of this specification is to enable Agencies to create, revise, and publ
 - Cap allowances (e.g. "Up to 500 additional scooters are permitted near train stations")
 - Speed-limit restrictions (e.g. "15 mph outside of downtown, 10 mph downtown")
 - Idle-time and disabled-time limitations (e.g. "5 days idle while rentable, 12 hours idle while unrentable, per device")
+- Trip fees and subsidies (e.g. "A 25 cent fee applied when a trip ends downtown")
 
 The machine-readable format allows Providers to obtain policies and compute compliance where it can be determined entirely by data obtained internally.
 
@@ -183,6 +184,7 @@ An individual `Policy` object is defined by the following fields:
 | `policy_id`      | UUID            | Required   | Unique ID of policy                                                                 |
 | `provider_ids`   | UUID[]          | Optional    | Providers for whom this policy is applicable; empty arrays and `null`/absent implies all Providers |
 | `description`    | String          | Required   | Description of policy                                                               |
+| `currency`       | String          | Optional   | An ISO 4217 Alphabetic Currency Code representing the [currency](../provider#costs--currencies) of all Rules of [type](#rule-types) `rate`.|
 | `start_date`     | [timestamp][ts] | Required   | Beginning date/time of policy enforcement                                           |
 | `end_date`       | [timestamp][ts] | Optional    | End date/time of policy enforcement                                                 |
 | `published_date` | [timestamp][ts] | Required   | Timestamp that the policy was published                                             |
@@ -205,6 +207,8 @@ An individual `Rule` object is defined by the following fields:
 | `propulsion_types` | `propulsion_type[]`         | Optional   | Applicable vehicle [propulsion types][propulsion-types], default "all". |
 | `minimum`          | integer                     | Optional   | Minimum value, if applicable (default 0) |
 | `maximum`          | integer                     | Optional   | Maximum value, if applicable (default unlimited) |
+| `rate_amount`      | integer                     | Optional   | The amount of a rate applied when this rule applies, if applicable (default zero). A positive integer rate amount represents a fee, while a negative integer represents a subsidy. Rate amounts are given in the `currency` defined in the [Policy](#policy). |
+| `rate_recurrence`  | enum                        | Optional   | Recurrence of the rate (see [Rate Recurrences](#rate-recurrences)) |
 | `start_time`       | ISO 8601 time `hh:mm:ss`              | Optional   | Beginning time-of-day when the rule is in effect (default 00:00:00). |
 | `end_time`         | ISO 8601 time `hh:mm:ss`              | Optional   | Ending time-of-day when the rule is in effect (default 23:59:59). |
 | `days`             | day[]                       | Optional   | Days `["sun", "mon", "tue", "wed", "thu", "fri", "sat"]` when the rule is in effect (default all) |
@@ -218,6 +222,7 @@ An individual `Rule` object is defined by the following fields:
 | `count` | Fleet counts based on regions. Rule `max`/`min` refers to number of devices.                                  |
 | `time`  | Individual limitations on time spent in one or more vehicle-states. Rule `max`/`min` refers to increments of time in [Rule Units](#rule-units). |
 | `speed` | Global or local speed limits. Rule `max`/`min` refers to speed in [Rule Units](#rule-units).                  |
+| `rate`  | **[Beta feature](/general-information.md#beta-features):** Yes (as of 1.0.0). Fees or subsidies based on regions and time spent in one or more vehicle-states. Rule `rate_amount` refers to the rate charged according to the [Rate Recurrence](#rate_recurrence). Agencies and Providers must agree on terms of use prior to utilizing the `rate` rule type.     |
 | `user`  | Information for users, e.g. about helmet laws. Generally can't be enforced via events and telemetry.          |
 
 ### Rule Units
@@ -227,9 +232,19 @@ An individual `Rule` object is defined by the following fields:
 | `seconds` | Seconds             |
 | `minutes` | Minutes             |
 | `hours`   | Hours               |
+| `days`    | Days                |
 | `mph`     | Miles per hour      |
 | `kph`     | Kilometers per hour |
 
+### Rate Recurrences
+Rate recurrences specify when a rate is applied – either once, or periodically according to a `time_unit` specified using [Rule Units](#rule-units). A `time_unit` refers to a unit of time as measured in local time for the juristiction – a day begins at midnight local time, an hour begins at the top of the hour, etc.
+
+| Name      | Description         |
+| --------- | ------------------- |
+| `once`                      |  Rate is applied once to vehicles entering a matching status from a non-matching status.   |     
+| `each_time_unit`            |  During each `time_unit`, rate is applied once to vehicles entering or remaining in a matching status. Requires a `time_unit` to be specified using `rule_units`.  |  
+| `per_complete_time_unit`    | Rate is applied once per complete `time_unit` that vehicles remain in a matching status. Requires a `time_unit` to be specified using `rule_units`.  | 
+
 ### Messages
 
 Some Policies as established by the Agency may benefit from rider communication. This optional field contains a map of languages to messages, to be shown to the user.

policy/examples.md

@@ -8,6 +8,9 @@ This file presents a series of [Policy object](./README.md#policy) examples for
 - [Provider Cap](#provider-cap)
 - [Idle Time](#idle-time)
 - [Speed Limits](#speed-limits)
+- [Per Trip Fees](#per-trip-fees)
+- [Vehicle Right of Way Fees](#vehicle-right-of-way-fees)
+- [Metered Parking Fees](#metered-parking-fees)
 
 ## Prohibited Zone
 
@@ -219,5 +222,99 @@ This Policy sets a 15 MPH speed limit in greater LA, and a 10 MPH speed limit in
   }]
 }
 ```
+[Top](#table-of-contents)
+
+## Per Trip Fees
+This policy sets a 25 cent per-trip fee that is applied for trips that start in the municipal boundary.
+
+
+```json
+{
+      "policy_id": "d2567b3c-3071-48a6-bbeb-3424721dbd12",
+      "published_date": 1586736000000,
+      "name": "Trip Fees",
+      "start_date": 1586822400000,
+      "end_date": 1587427200000,
+      "prev_policies": null,
+      "rules": [{
+    		  "name": "City Wide Trip Fee",
+    		  "rule_type": "rate",
+    		  "rate_amount": 25,
+    		  "rate_recurrence": "once",
+    		  "geography": MUNICIPAL_BOUNDARY_GEOGRAPHY,
+    		  "statuses": {
+    		        "trip": ["trip_start"]
+    		   }
+    		}]
+    }
+```
+[Top](#table-of-contents)
+
+## Vehicle Right of Way Fees
+This policy sets a Right-of-Way fee that is charged once a day for vehicles deployed in a given area. It charges a 25 cents per day for vehicles deployed downtown, and 5 cents per day for vehicles deployed in a historically underserved neighborhood. In the case where a vehicle is deployed twice in both areas in the same day, the higher fee would apply (because it appears first in the rules).
 
+```json
+{
+      "policy_id": "4137a47c-836a-11ea-bc55-0242ac130003",
+      "published_date": 1586736000000,
+      "name": "Right of Way Fees",
+      "start_date": 1586822400000,
+      "end_date": 1587427200000,
+      "prev_policies": null,
+      "rules": [
+    			{
+    			  "name": "Downtown Right of Way Fee",
+    			  "rule_type": "rate",
+    			  "rate_amount": 25,
+    			  "rate_recurrence": "each_time_unit",
+    			  "rule_units": "days",
+    			  "geography": DOWNTOWN_GEOGRAPHY,
+    			  "statuses": {
+    			        "available": ["service_start"]
+    			   }
+    			},
+    			{
+    			  "name": "Decreased Right of Way Fee",
+    			  "rule_type": "rate",
+    			  "rate_amount": 5,
+    			  "rate_recurrence": "each_time_unit",
+    			  "rule_units": "days",
+    			  "geography": HISTORICALLY_UNDERSERVED_NEIGHBORHOOD_GEOGRAPHY,
+    			  "statuses": {
+    			        "available": ["service_start"]
+    			   }
+    			}
+    		]
+    }
+```
+[Top](#table-of-contents)
+
+## Metered Parking Fees
+This policy sets a 10 cent per hour metered parking charge that is applied while a vehicle is parked in a congested area during rush hour.
+
+```json
+{
+      "policy_id": "6a3dd008-836a-11ea-bc55-0242ac130003",
+      "published_date": 1586736000000,
+      "name": "Parking Fees",
+      "start_date": 1586822400000,
+      "end_date": 1587427200000,
+      "prev_policies": null,
+      "rules": [{
+    		  "name": "Downtown Peak-Hour Parking Fee",
+    		  "rule_type": "rate",
+    		  "rate_amount": 10,
+    		  "rate_recurrence": "per_complete_time_unit",
+    		  "rule_units": "hours",
+    		  "geography": INNER_CITY_GEOGRAPHY,
+    		  "days": ["mon","tue","wed","thu","fri"],
+    		  "start_time": "7:00:00",
+    		  "end_time": "8:30:00",
+    		  "statuses": {
+    		        "available": [],
+    		        "unavailable": [],
+    		   }
+    		}]
+    }
+```
 [Top](#table-of-contents)