Skip to content

Commit

Permalink
Merge pull request #817 from openmobilityfoundation/feature-remove-ra…
Browse files Browse the repository at this point in the history 
…te-policy-type

Remove 'rate' rule-type, since we can put rate_amount on any rule
  • Loading branch information
@schnuerle
schnuerle authored Jan 18, 2023
2 parents 3e47dbd + 198af64 commit 8a83e1f
Show file tree
Hide file tree
Showing 3 changed files with 53 additions and 37 deletions.
26 changes: 12 additions & 14 deletions policy/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -267,7 +267,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. See MDS [provider list](/providers.csv). |
| `description` | String | Required | Description of policy |
| `currency` | String | Optional | An ISO 4217 Alphabetic Currency Code representing the [currency](../general-information.md#costs-and-currencies) of all Rules of [type](#rule-types) `rate`.|
| `currency` | String | Optional | An ISO 4217 Alphabetic Currency Code representing the [currency](../general-information.md#costs-and-currencies) of all Rules with a `rate_amount`.|
| `start_date` | [timestamp][ts] | Required | Beginning date/time of policy enforcement. In order to give providers sufficient time to poll, `start_date` must be at least 20 minutes after `published_date`. |
| `end_date` | [timestamp][ts] | Optional | End date/time of policy enforcement |
| `published_date` | [timestamp][ts] | Required | Timestamp that the policy was published |
Expand Down Expand Up @@ -313,23 +313,21 @@ An individual `Rule` object is defined by the following fields:
| `count` | Fleet counts based on regions. Rule `minimum`/`maximum` refers to number of devices in [Rule Units](#rule-units). |
| `time` | Individual limitations or fees based upon time spent in one or more vehicle states. Rule `minimum`/`maximum` refers to increments of time in [Rule Units](#rule-units). |
| `speed` | Global or local speed limits. Rule `minimum`/`maximum` 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 Recurrences](#rate_recurrences) and the [currency requirements](/general-information.md#costs-and-currencies) in [Rule Units](#rule-units). *Prior to implementation agencies should consult with providers to discuss how the `rate` rule will be used. Most agencies do this as a matter of course, but it is particularly important to communicate in advance how frequently and in what ways rates might change over time.* |
| `user` | Information for users, e.g. about helmet laws. Generally can't be enforced via events and telemetry. |

[Top][toc]

### Rule Units

| Name | Rule Types | Description |
| --------- | ---------------------- | ------------------- |
| `seconds` | `rate`, `time` | Seconds |
| `minutes` | `rate`, `time` | Minutes |
| `hours` | `rate`, `time` | Hours |
| `days` | `rate`, `time` | Days |
| `amount` | `rate` | Cost (in [local currency](/general-information.md#costs-and-currencies)) |
| `mph` | `speed` | Miles per hour |
| `kph` | `speed` | Kilometers per hour |
| `devices` | `count` | Devices |
| Name | Rule Types | Description |
| --------- | -------------- | ------------------- |
| `seconds` | `time` | Seconds |
| `minutes` | `time` | Minutes |
| `hours` | `time` | Hours |
| `days` | `time` | Days |
| `mph` | `speed` | Miles per hour |
| `kph` | `speed` | Kilometers per hour |
| `devices` | `count` | Devices |

[Rule type](#rule-types) `user` has no associated Rule units; `rule_units` is not required when the Rule type is `user`.

Expand All @@ -352,9 +350,9 @@ An individual `Rule` object is defined by the following fields:
[Top][toc]

### Rates
Rate-related properties can currently be specified on `rate` and `time` Rules. Note: A future MDS version will likely support rates for `count` and `speed` rules, but their behavior is currently undefined.
Rate-related properties can currently be specified on all rule types except `user`, i.e. any rule that can be measured.

**[Beta feature](/general-information.md#beta-features)**: *Yes (as of 1.0.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/674)
**[Beta feature](/general-information.md#beta-features)**: *No (as of 2.0.0)*. [Leave feedback](https://github.com/openmobilityfoundation/mobility-data-specification/issues/674)

#### Rate Amounts
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).
Expand Down
6 changes: 1 addition & 5 deletions policy/policy.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,6 @@
"count",
"time",
"speed",
"rate",
"user"
]
},
Expand Down Expand Up @@ -328,9 +327,6 @@
"rate_recurrence"
],
"properties": {
"rule_type": {
"const": "rate"
},
"rule_units": {
"enum": [
"amount",
Expand Down Expand Up @@ -646,4 +642,4 @@
}
},
"additionalProperties": false
}
}
58 changes: 40 additions & 18 deletions schema/templates/policy/policy.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@
"$ref": "#/definitions/uuid",
"description": "Unique ID of policy"
},
"provider_ids":{
"provider_ids": {
"$id": "#/definitions/policy/properties/provider_ids",
"$ref": "#/definitions/null_uuid_array",
"description": "Providers for whom this policy is applicable; empty arrays and null/absent implies all Providers.",
Expand All @@ -43,7 +43,7 @@
"$id": "#/definitions/policy/properties/currency",
"$ref": "#/definitions/currency"
},
"start_date":{
"start_date": {
"$id": "#/definitions/policy/properties/start_date",
"$ref": "#/definitions/timestamp",
"description": "Beginning date/time of policy enforcement"
Expand Down Expand Up @@ -107,7 +107,6 @@
"count",
"time",
"speed",
"rate",
"user"
]
},
Expand All @@ -126,8 +125,7 @@
"$id": "#/definitions/rule/properties/states/propertyNames",
"$ref": "#/definitions/vehicle_state"
},
"properties": {
},
"properties": {},
"additionalProperties": {
"type": "array",
"uniqueItems": true,
Expand Down Expand Up @@ -163,32 +161,50 @@
},
"minimum": {
"$id": "#/definitions/rule/properties/minimum",
"type": ["null", "integer"],
"type": [
"null",
"integer"
],
"description": "Minimum value, if applicable (default 0)"
},
"maximum": {
"$id": "#/definitions/rule/properties/maximum",
"type": ["null", "integer"],
"type": [
"null",
"integer"
],
"description": "Maximum value, if applicable (default unlimited)"
},
"inclusive_minimum": {
"$id": "#/definitions/rule/properties/inclusive_minimum",
"type": ["null", "boolean"],
"type": [
"null",
"boolean"
],
"description": "Whether the rule minimum is considered in-bounds (default true)"
},
"inclusive_maximum": {
"$id": "#/definitions/rule/properties/inclusive_maximum",
"type": ["null", "boolean"],
"type": [
"null",
"boolean"
],
"description": "Whether the rule maximum is considered in-bounds (default true)"
},
"rate_amount": {
"$id": "#/definitions/rule/properties/rate_amount",
"type": ["null", "integer"],
"type": [
"null",
"integer"
],
"description": "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."
},
"rate_recurrence": {
"$id": "#/definitions/rule/properties/rate_recurrence",
"type": ["string", "null"],
"type": [
"string",
"null"
],
"description": "Specify how a rate is applied – either once, or periodically according to a time unit specified using rule_units",
"enum": [
"once_on_match",
Expand All @@ -199,7 +215,10 @@
},
"rate_applies_when": {
"$id": "#/definitions/rule/properties/rate_applies_when",
"type": ["string", "null"],
"type": [
"string",
"null"
],
"description": "Specify when a rate is applicable to an event or count: when it's within rule bounds or when it is not",
"enum": [
"in_bounds",
Expand All @@ -223,15 +242,21 @@
},
"messages": {
"$id": "#/definitions/rule/properties/messages",
"type": ["null", "object"],
"type": [
"null",
"object"
],
"description": "Message to rider user, if desired, in various languages, keyed by BCP 47 language tag",
"propertyNames": {
"pattern": "([A-Za-z]{2,3})([-][A-Za-z]{3}){0,3}([-]([A-Za-z]{4}))?([-]([A-Za-z]{2}|[0-9]{3}))?"
}
},
"value_url": {
"$id": "#/definitions/rule/properties/value_url",
"type": ["null", "string"],
"type": [
"null",
"string"
],
"description": "URL to an API endpoint that can provide dynamic information for the measured value",
"format": "uri"
}
Expand Down Expand Up @@ -302,9 +327,6 @@
"rate_recurrence"
],
"properties": {
"rule_type": {
"const": "rate"
},
"rule_units": {
"enum": [
"amount",
Expand Down Expand Up @@ -368,4 +390,4 @@
}
},
"additionalProperties": false
}
}

0 comments on commit 8a83e1f

Please sign in to comment.