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

Policy JSON Schema #576

Merged
merged 21 commits into from
Sep 15, 2020
Merged

Policy JSON Schema #576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
e04170b
add missing links
thekaveman Aug 13, 2020
be46173
stub the Policy schema generator
thekaveman Aug 13, 2020
55902d2
starting basic schema template
thekaveman Aug 13, 2020
4a58b1b
forgot wrapper info
thekaveman Aug 14, 2020
6a22885
filling out required policy fields
thekaveman Aug 14, 2020
756c169
refactor common definitions access
thekaveman Aug 14, 2020
59ace40
elevate the main policy object to definitions
thekaveman Aug 14, 2020
215c5aa
required fields for rule definition
thekaveman Aug 14, 2020
d20955d
normalizing common structures for propulsion and vehicle type
thekaveman Aug 17, 2020
3c56a5f
adding more common definitions to fill out rule
thekaveman Aug 17, 2020
d8fcc38
the rule states object schema
thekaveman Aug 17, 2020
fc74c1c
moving currency definition to common for reuse
thekaveman Aug 17, 2020
c5b12e3
define an array of uuid type
thekaveman Aug 17, 2020
5d4b19c
add the remaining optional policy fields
thekaveman Aug 17, 2020
654295a
allow for nullable type definitions
thekaveman Sep 12, 2020
acbf370
clean up examples so they validate
thekaveman Sep 12, 2020
664cf9d
adding the policy JSON schema
thekaveman Sep 12, 2020
b7e31d1
add validation for rule_type and rule_units
thekaveman Sep 12, 2020
788e3d9
add a set of complete, valid sample documents
thekaveman Sep 12, 2020
f9727e3
regenerate all schemas again
thekaveman Sep 12, 2020
a09d3be
optimize the common definitions deepcopy
thekaveman Sep 14, 2020
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
16 changes: 11 additions & 5 deletions agency/get_stops.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,11 +111,8 @@
},
"devices": {
"$id": "#/definitions/stop/properties/devices",
"type": "array",
"description": "List of device_id for vehicles currently at this Stop.",
"items": {
"$ref": "#/definitions/uuid"
}
"$ref": "#/definitions/uuid_array",
"description": "List of device_id for vehicles currently at this Stop."
}
}
},
Expand Down Expand Up @@ -171,6 +168,15 @@
],
"pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$"
},
"uuid_array": {
"$id": "#/definitions/uuid_array",
"type": "array",
"description": "Array of UUID",
"items": {
"$id": "#/definitions/uuid_array/items",
"$ref": "#/definitions/uuid"
}
},
"vehicle_type_counts": {
"$id": "#/definitions/vehicle_type_counts",
"type": "object",
Expand Down
31 changes: 13 additions & 18 deletions agency/get_vehicle.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,12 @@
"propulsion_types": {
"$id": "#/definitions/propulsion_types",
"type": "array",
"description": "The type of propulsion; allows multiple values",
"description": "Array of propulsion types, allowing multiple values",
"items": {
"type": "string",
"enum": [
"combustion",
"electric",
"electric_assist",
"human"
]
"$id": "#/definitions/propulsion_types/items",
"$ref": "#/definitions/propulsion_type"
},
"uniqueItems": true,
"minItems": 1
"uniqueItems": true
},
"string": {
"$id": "#/definitions/string",
Expand All @@ -31,6 +25,13 @@
],
"pattern": "^(.*)$"
},
"timestamp": {
"$id": "#/definitions/timestamp",
"type": "number",
"description": "Integer milliseconds since Unix epoch",
"multipleOf": 1.0,
"minimum": 0
},
"vehicle_type": {
"$id": "#/definitions/vehicle_type",
"type": "string",
Expand All @@ -43,13 +44,6 @@
"other"
]
},
"timestamp": {
"$id": "#/definitions/timestamp",
"type": "number",
"description": "Integer milliseconds since Unix epoch",
"multipleOf": 1.0,
"minimum": 0
},
"uuid": {
"$id": "#/definitions/uuid",
"type": "string",
Expand Down Expand Up @@ -155,7 +149,8 @@
"propulsion_types": {
"$id": "#/definitions/vehicle/properties/propulsion_types",
"$ref": "#/definitions/propulsion_types",
"description": "The type of propulsion; allows multiple values"
"description": "The type of propulsion; allows multiple values",
"minItems": 1
},
"year": {
"$id": "#/properties/year",
Expand Down
16 changes: 11 additions & 5 deletions agency/post_stops.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,11 +111,8 @@
},
"devices": {
"$id": "#/definitions/stop/properties/devices",
"type": "array",
"description": "List of device_id for vehicles currently at this Stop.",
"items": {
"$ref": "#/definitions/uuid"
}
"$ref": "#/definitions/uuid_array",
"description": "List of device_id for vehicles currently at this Stop."
}
}
},
Expand Down Expand Up @@ -171,6 +168,15 @@
],
"pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$"
},
"uuid_array": {
"$id": "#/definitions/uuid_array",
"type": "array",
"description": "Array of UUID",
"items": {
"$id": "#/definitions/uuid_array/items",
"$ref": "#/definitions/uuid"
}
},
"vehicle_type_counts": {
"$id": "#/definitions/vehicle_type_counts",
"type": "object",
Expand Down
17 changes: 6 additions & 11 deletions agency/post_vehicle.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,18 +7,12 @@
"propulsion_types": {
"$id": "#/definitions/propulsion_types",
"type": "array",
"description": "The type of propulsion; allows multiple values",
"description": "Array of propulsion types, allowing multiple values",
"items": {
"type": "string",
"enum": [
"combustion",
"electric",
"electric_assist",
"human"
]
"$id": "#/definitions/propulsion_types/items",
"$ref": "#/definitions/propulsion_type"
},
"uniqueItems": true,
"minItems": 1
"uniqueItems": true
},
"string": {
"$id": "#/definitions/string",
Expand Down Expand Up @@ -79,7 +73,8 @@
"propulsion_types": {
"$id": "#/definitions/vehicle/properties/propulsion_types",
"$ref": "#/definitions/propulsion_types",
"description": "The type of propulsion; allows multiple values"
"description": "The type of propulsion; allows multiple values",
"minItems": 1
},
"year": {
"$id": "#/properties/year",
Expand Down
50 changes: 30 additions & 20 deletions policy/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ Versioning must be implemented as specified in the [Versioning section][versioni

## Background

The goal of this specification is to enable Agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both _mobility as a service_ Providers and riders / users. [Examples](examples.md) of policies include:
The goal of this specification is to enable Agencies to create, revise, and publish machine-readable policies, as sets of rules for individual and collective device behavior exhibited by both _mobility as a service_ Providers and riders / users. [Examples](./examples/README.md) of policies include:

- City-wide and localized caps (e.g. "Minimum 500 and maximum 3000 scooters within city boundaries")
- Exclusion zones (e.g. "No scooters are permitted in this district on weekends")
Expand All @@ -50,7 +50,7 @@ The goal of this specification is to enable Agencies to create, revise, and publ

The machine-readable format allows Providers to obtain policies and compute compliance where it can be determined entirely by data obtained internally.

**See the [Policy Examples](examples.md) for ways these can be implemented.**
**See the [Policy Examples](./examples/README.md) for ways these can be implemented.**

[Top][toc]

Expand Down Expand Up @@ -139,7 +139,7 @@ The `updated` field in the payload wrapper should be set to the time of publishi

#### Example `policies.json`

```json
```jsonc
{
"version": "0.4.0",
"updated": 1570035222868,
Expand All @@ -161,7 +161,7 @@ The optional `end_date` field applies to all policies represented in the file.

#### Example `geographies.json`

```json
```jsonc
{
"version": "0.4.0",
"updated": 1570035222868,
Expand All @@ -186,7 +186,7 @@ All response fields must use `lower_case_with_underscores`.

Response bodies must be a `UTF-8` encoded JSON object and must minimally include the MDS `version`, a timestamp indicating the last time the data was `updated`, and a `data` payload:

```json
```jsonc
{
"version": "x.y.z",
"updated": 1570035222868,
Expand All @@ -196,6 +196,12 @@ Response bodies must be a `UTF-8` encoded JSON object and must minimally include
}
```

### JSON Schema

The JSON Schema file is available in this repository: [`policy.json`](./policy.json).

Before publishing a new Policy document, the document should be validated against the schema to ensure it has the correct format and fields.

[Top][toc]

### Policy
Expand All @@ -208,7 +214,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](../provider#costs--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 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 |
Expand All @@ -227,8 +233,8 @@ An individual `Rule` object is defined by the following fields:
| `rule_id` | UUID | Required | Unique ID of the rule |
| `rule_type` | enum | Required | Type of policy (see [Rule Types](#rule-types)) |
| `geographies` | UUID[] | Required | List of Geography UUIDs (non-overlapping) specifying the covered geography |
| `states` | `{ state: event[] }` | Required | [Vehicle state][vehicle-states] to which this rule applies. Optionally provide a list of specific [vehicle events][#vehicle-events] as a subset of a given status for the rule to apply to. An empty list or `null`/absent defaults to "all". |
| `rule_units` | enum | Required | Measured units of policy (see [Rule Units](#rule-units)) |
| `states` | `{ state: event[] }` | Required | [Vehicle state][vehicle-states] to which this rule applies. Optionally provide a list of specific [vehicle events][#vehicle-events] as a subset of a given status for the rule to apply to. An empty list or `null`/absent defaults to "all". |
| `rule_units` | enum | Conditionally Required | Measured units of policy (see [Rule Units](#rule-units)) |
| `vehicle_types` | `vehicle_type[]` | Optional | Applicable vehicle types, default "all". |
| `propulsion_types` | `propulsion_type[]` | Optional | Applicable vehicle [propulsion types][propulsion-types], default "all". |
| `minimum` | integer | Optional | Minimum value, if applicable (default 0) |
Expand Down Expand Up @@ -257,16 +263,18 @@ An individual `Rule` object is defined by the following fields:

### Rule Units

| 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 |
| `amount` | `rate` | Cost (in [local currency](/general-information.md#costs-and-currencies)) |
| 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 |

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

[Top][toc]

Expand All @@ -290,9 +298,9 @@ Rate recurrences specify when a rate is applied – either once, or periodicall

| Name | Description |
| --------- | ------------------- |
| `once` | Rate is applied once to vehicles entering a matching status from a non-matching status. |
| `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`. |
| `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`. |

[Top][toc]

Expand Down Expand Up @@ -344,9 +352,11 @@ The internal mechanics of ordering are up to the Policy editing and hosting soft
[Top][toc]

[beta]: /general-information.md#beta
[error-messages]: /general-information.md#error-messages
[iana]: https://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml
[muni-boundary]: ../provider/README.md#municipality-boundary
[propulsion-types]: /general-information.md#propulsion-types
[responses]: /general-information.md#responses
[ts]: /general-information.md#timestamps
[toc]: #table-of-contents
[vehicle-events]: /general-information.md#vehicle-state-events
Expand Down
Loading