Merge pull request #939 from openmobilityfoundation/feature-conditional-optional

Conditional and Optional field definitions

Author: schnuerle

data-types.md

@@ -6,6 +6,7 @@ This document contains specifications that are shared between the various MDS [A
 
 - [Authorization](#authorization)
 - [Beta Features](#beta-features)
+- [Conditionally Required Fields](#conditionally-required-fields)
 - [Costs and Currencies](#costs-and-currencies)
 - [Data Types](#data-types)
 - [Definitions](#definitions)
@@ -14,6 +15,7 @@ This document contains specifications that are shared between the various MDS [A
 - [Geographic Data](#geographic-data)
   - [Intersection Operation](#intersection-operation)
 - [Geography-Driven Events](#geography-driven-events)
+- [Optional Fields](#optional-fields)
 - [Responses](#responses)
   - [Error Messages](#error-messages)
   - [Bulk Responses](#bulk-responses)
@@ -83,6 +85,12 @@ Working Groups and their Steering Committees are expected to review beta designa
 
 [Top][toc]
 
+## Conditionally Required Fields
+
+Conditionally required fields **must** be provided in MDS data feeds from operators if the data is available from the operator, and/or the public agency requests it as part of its permit, RFP, contract, operating agreement, SLA, [Requirements](./policy#requirement) file, or via other authority. Or as part of the conditional requirement as stated in the field's descritpion.
+
+[Top][toc]
+
 ## Costs and Currencies
 
 Fields specifying a monetary cost use a currency as specified in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217#Active_codes). All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of `100` (100 cents).
@@ -167,6 +175,12 @@ During the Beta period for this feature, location and telemetry data remain requ
 
 [Top][toc]
 
+## Optional Fields
+
+Optional fields **may** be provided in MDS data feeds from operators if the data is available from the operator, and/or the public agency requests it as part of its permit, RFP, contract, operating agreement, SLA, [Requirements](./policy#requirement) file, or via other authority. 
+
+[Top][toc]
+
 ## Responses
 
 - **200:** OK: operation successful.

general-information.md

@@ -89,14 +89,14 @@ See the [Endpoints](#endpoints) below for links to specific data objects, and th
 | Name               | Type      | Required/Optional | Description                                                                     |
 | ----------------   | --------- | --- | --------------------------------------------------------------------------------------------- |
 | `name`             | String    | Required   | Name of geography                                                                      |
-| `description`      | String    | Optional   | Detailed description of geography                                                      |
-| `geography_type`   | String     | Optional   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Type](#geography-type). |
+| `description`      | String    | [Optional](../general-information.md#optional-fields)   | Detailed description of geography                                                      |
+| `geography_type`   | String     | [Optional](../general-information.md#optional-fields)   | Type of geography, e.g. `municipal_boundary` or `council_district` or custom text.  See [Geography Type](#geography-type). |
 | `geography_id`     | UUID      | Required   | Unique ID of geography                                                                 |
 | `geography_json`   | JSON      | Required   | The GeoJSON that defines the geographical coordinates.                                 |
-| `effective_date`   | [timestamp][ts] | Optional   | The date at which a Geography is considered "live".  Must be at or after `published_date`. |
+| `effective_date`   | [timestamp][ts] | [Optional](../general-information.md#optional-fields)   | The date at which a Geography is considered "live".  Must be at or after `published_date`. |
 | `published_date`     | [timestamp][ts] | Required   | Time that the geography was published, i.e. made immutable                       |
-| `retire_date`     | [timestamp][ts] | Optional   | Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after `effective_date`. Geographies referencing others with `prev_geographies` immediately replace the previous ones. |
-| `prev_geographies` | UUID[]    | Optional   | Unique IDs of prior geographies replaced by this one                                   |
+| `retire_date`     | [timestamp][ts] | [Optional](../general-information.md#optional-fields)   | Time that the geography is slated to retire. Once the retire date is passed, new policies can no longer reference it and old policies referencing it should be updated. Retired geographies should continue to be returned in the geographies list. Must be after `effective_date`. Geographies referencing others with `prev_geographies` immediately replace the previous ones. |
+| `prev_geographies` | UUID[]    | [Optional](../general-information.md#optional-fields)   | Unique IDs of prior geographies replaced by this one                                   |
 
 [Top][toc]
 

geography/README.md

@@ -98,9 +98,9 @@ An individual `Jurisdiction` object is defined by the following fields:
 | ----------------- | --------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `jurisdiction_id` | UUID      | Required            | Unique ID of Jurisdiction. This field is immutable.                                                                                                                                                                                                                                                                   |
 | `agency_key`      | String    | Required            | A unique string key for the Jurisdiction. This field must also be immutable. Allows for easier management of Jurisdiction-based access control in JWTs.                                                                                                                                                               |
-| `agency_name`     | String    | Optional            | Human-readable agency name for display purposes.                                                                                                                                                                                                                                                                      |
+| `agency_name`     | String    | [Optional](../general-information.md#optional-fields)            | Human-readable agency name for display purposes.                                                                                                                                                                                                                                                                      |
 | `description`     | String    | Required            | Description of Jurisdiction.                                                                                                                                                                                                                                                                                          |
-| `geography_id`    | UUID      | Optional            | The unique ID of the geography covered by this Jurisdiction.                                                                                                                                                                                                                                                          |
+| `geography_id`    | UUID      | [Optional](../general-information.md#optional-fields)            | The unique ID of the geography covered by this Jurisdiction.                                                                                                                                                                                                                                                          |
 | `mode_ids`  | String[]  | Required            | Use this field to specify an array of what mobility [modes][modes] a jurisdiction applies to. |
 | `timestamp`       | timestamp | Required            | Creation or update time of a Jurisdiction.                                                                                                                                                                                                                                                                            |
 

jurisdiction/README.md

@@ -54,7 +54,7 @@ The `journey_id` field shall have a consistent value in overlapping trips for a
 
 The `journey_attributes` object **may** have the following key value pairs:
 
-- `reservation_id` (UUID, optional): unique identifier for an entire car share reservation, tied across multiple journeys and therefore trips.
+- `reservation_id` (UUID, [Optional](../general-information.md#optional-fields)): unique identifier for an entire car share reservation, tied across multiple journeys and therefore trips.
 
 [Top][toc]
 
@@ -81,9 +81,9 @@ The `trip_type` field **must** have one of the following enumerated values:
 The `trip_attributes` object **may** have the following key value pairs:
 
 - `reservation_type` (enumerated, required): how was the vehicle reserved, one of `phone_dispatch`, `phone`, `text`, `app`
-- `app_name` (text, optional): name of the app used to reserve the vehicle which could be provider's app or 3rd party app
-- `permit_license_number` (string, optional) - The permit license number of the organization that dispatched the vehicle
-- `driver_id` (string, optional): Universal identifier of a specific driver, static across operators, like a driver's license number, for company employees in `reservation` or `empty` trip types, not `private` trips. Could also be used as a lookup in an agency's internal driver system.
+- `app_name` (text, [Optional](../general-information.md#optional-fields)): name of the app used to reserve the vehicle which could be provider's app or 3rd party app
+- `permit_license_number` (string, [Optional](../general-information.md#optional-fields)) - The permit license number of the organization that dispatched the vehicle
+- `driver_id` (string, [Optional](../general-information.md#optional-fields)): Universal identifier of a specific driver, static across operators, like a driver's license number, for company employees in `reservation` or `empty` trip types, not `private` trips. Could also be used as a lookup in an agency's internal driver system.
 
 [Top][toc]
 
@@ -93,14 +93,14 @@ The `fare_attributes` object **may** have the following key value pairs:
 
 - `payment_type` (enumerated, required): `account_number`, `cash`, `credit_card`, `mobile_app`, `no payment`, `phone`, `voucher`, `test`
 - `fare_type` (enumerated, required): `meter_fare`, `upfront_pricing`, `flat_rate`. Indicator of which rate was charged.
-- `tolls` (currency, optional) - Sum of any and all tolls charged for the trip, such as bridge tolls
-- `base_rate` (currency, optional) - Minimum fare to be charged as soon as the trip starts.
-- `exit_fee` (currency, optional) - Fee to exit location, like an airport
-- `other_fees` (currency, optional) - amount of any fees charged to the customer. Includes baggage fees, cleaning fee. Excludes other fees returned.
-- `tip` (currency, optional) - amount of tip paid by customer
-- `extra_amount` (currency, optional) - miscellaneous extra amounts charged to customer not covered by other fields.
-- `taxes` (currency, optional) - amount of taxes paid for the ride
-- `surcharge` (currency, optional) - any surcharge pricing
+- `tolls` (currency, [Optional](../general-information.md#optional-fields)) - Sum of any and all tolls charged for the trip, such as bridge tolls
+- `base_rate` (currency, [Optional](../general-information.md#optional-fields)) - Minimum fare to be charged as soon as the trip starts.
+- `exit_fee` (currency, [Optional](../general-information.md#optional-fields)) - Fee to exit location, like an airport
+- `other_fees` (currency, [Optional](../general-information.md#optional-fields)) - amount of any fees charged to the customer. Includes baggage fees, cleaning fee. Excludes other fees returned.
+- `tip` (currency, [Optional](../general-information.md#optional-fields)) - amount of tip paid by customer
+- `extra_amount` (currency, [Optional](../general-information.md#optional-fields)) - miscellaneous extra amounts charged to customer not covered by other fields.
+- `taxes` (currency, [Optional](../general-information.md#optional-fields)) - amount of taxes paid for the ride
+- `surcharge` (currency, [Optional](../general-information.md#optional-fields)) - any surcharge pricing
 
 [Top][toc]
 
@@ -118,23 +118,23 @@ The `vehicle_attributes` object **may** have the following key value pairs:
 - `color` (string, required)
 - `vin` (string, required) - the Vehicle Identification Number of the vehicle
 - `license_plate` (string, required) - the registered external license plate number of the vehicle
-- `inspection_date` (date YYYY-MM-DD, optional) - the date of the last inspection of the vehicle
-- `snow_shovel` (boolean, optional) - shovel for removing snow or ice from around vehicle or vehicle path
-- `snow_brush` (boolean, optional) - brushes for removing snow or ice from vehicle
-- `bike_rack` (boolean, optional) - car roof or trunk mounted bike rack
-- `park_access` (boolean, optional) - access pass to a national/regional/municipal park system
-- `toll_transponder` (boolean, optional) - toll transponder for national/regional toll system
-- `phone_charger` (boolean, optional) - a place to charge your phone
-- `sunshade` (boolean, optional) - sunshade available (i.e. for windshield)
-- `cargo_volume_capacity` (integer, optional) - Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
-- `cargo_load_capacity` (integer, optional) - The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms.
-- `door_count` (integer, optional) - number of doors this vehicle type has
-- `wheel_count` (integer, optional) - number of wheels this vehicle type has
-- `air_conditioning` (boolean, optional) - vehicle has air conditioning
-- `gear_switch` (enum, optional) - one of `automatic`, `manual`
-- `convertible` (boolean, optional) - vehicle has a retractable roof
-- `cruise_control` (boolean, optional) - vehicle has a cruise control system
-- `navigation` (boolean, optional) - vehicle has a built-in navigation system
+- `inspection_date` (date YYYY-MM-DD, [Optional](../general-information.md#optional-fields)) - the date of the last inspection of the vehicle
+- `snow_shovel` (boolean, [Optional](../general-information.md#optional-fields)) - shovel for removing snow or ice from around vehicle or vehicle path
+- `snow_brush` (boolean, [Optional](../general-information.md#optional-fields)) - brushes for removing snow or ice from vehicle
+- `bike_rack` (boolean, [Optional](../general-information.md#optional-fields)) - car roof or trunk mounted bike rack
+- `park_access` (boolean, [Optional](../general-information.md#optional-fields)) - access pass to a national/regional/municipal park system
+- `toll_transponder` (boolean, [Optional](../general-information.md#optional-fields)) - toll transponder for national/regional toll system
+- `phone_charger` (boolean, [Optional](../general-information.md#optional-fields)) - a place to charge your phone
+- `sunshade` (boolean, [Optional](../general-information.md#optional-fields)) - sunshade available (i.e. for windshield)
+- `cargo_volume_capacity` (integer, [Optional](../general-information.md#optional-fields)) - Cargo volume available in the vehicle, expressed in liters. For cars, it corresponds to the space between the boot floor, including the storage under the hatch, to the rear shelf in the trunk.
+- `cargo_load_capacity` (integer, [Optional](../general-information.md#optional-fields)) - The capacity of the vehicle cargo space (excluding passengers), expressed in kilograms.
+- `door_count` (integer, [Optional](../general-information.md#optional-fields)) - number of doors this vehicle type has
+- `wheel_count` (integer, [Optional](../general-information.md#optional-fields)) - number of wheels this vehicle type has
+- `air_conditioning` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has air conditioning
+- `gear_switch` (enum, [Optional](../general-information.md#optional-fields)) - one of `automatic`, `manual`
+- `convertible` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a retractable roof
+- `cruise_control` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a cruise control system
+- `navigation` (boolean, [Optional](../general-information.md#optional-fields)) - vehicle has a built-in navigation system
 
 Note many of these attributes come from fields in [GBFS vehicle_types](https://github.com/MobilityData/gbfs/blob/v2.3/gbfs.md#vehicle_typesjson).