Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Remove 'rate' rule-type, since we can put rate_amount on any rule #817

Merged
merged 1 commit into from
Jan 18, 2023
Merged

Remove 'rate' rule-type, since we can put rate_amount on any rule #817

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 12 additions & 14 deletions policy/README.md
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
}
}