MobilityData · barbeau · May 22, 2020 · Feb 19, 2019 · Feb 19, 2019 · Feb 19, 2019
diff --git a/gbfs.md b/gbfs.md
@@ -10,6 +10,7 @@ This document explains the types of files and data that comprise the General Bik
 * [Field Definitions](#field-definitions)
     * [gbfs.json](#gbfsjson)
     * [system_information.json](#system_informationjson)
+    * [vehicle_types.json](#vehicle_typesjson)
     * [station_information.json](#station_informationjson)
     * [station_status.json](#station_statusjson)
     * [free_bike_status.json](#free_bike_statusjson)
@@ -41,6 +42,7 @@ File Name                   | Required                |       Defines
 --------------------------- | ----------------------- | ----------
 gbfs.json                   | Optional                | Auto-discovery file that links to all of the other files published by the system. This file is optional, but highly recommended.
 system_information.json     | Yes                     | Describes the system including System operator, System location, year implemented, URLs, contact info, time zone
+vehicle_types.json     | Conditionally required                     | Describes the types of vehicles that System operator has available for rent. Required of systems that include information about vehicle types in the station_status and/or free_bike_status files. If this file is not included, then all vehicles in the feed are assumed to be non-motorized bicycles
 station_information.json    | Conditionally required  | Mostly static list of all stations, their capacities and locations. Required of systems utilizing docks.
 station_status.json         | Conditionally required  | Number of available bikes and docks at each station and station availability. Required of systems utilizing docks.
 free_bike_status.json       | Conditionally required  | Describes bikes that are available for rent. Required of systems that don't utilize docks or offer bikes for rent outside of stations.
@@ -173,6 +175,43 @@ email             | Optional  | A single contact email address for customers to
 timezone          | Yes       | The time zone where the system is located. Time zone names never contain the space character but may contain an underscore. Please refer to the "TZ" value in https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for a list of valid values
 license_url       | Optional  | A fully qualified URL of a page that defines the license terms for the GBFS data for this system, as well as any other license terms the system would like to define (including the use of corporate trademarks, etc)
 
+### vehicle_types.json
+The following fields are all attributes within the main "data" object for this feed.
+
+ield Name        | Required  | Defines
+------------------| --------- | ----------
+vehicle_types          | Yes       | Array that contains one object per vehicle type in the system as defined below
+\- vehicle_type_id      | Yes       | Unique identifier of a vehicle type. See [Field Definitions](#field-definitions) above for ID field requirements
+\- form_factor      | Yes       | An enumerable describing the vehicle's general form factor. <br /><br />Current valid values are:<br /><ul><li>`bicycle`</li><li>`scooter`</li><li>`car`</li></ul>
+\- propulsion_types | Yes | An array consisting of enumerables that describe the propulsion type of the vehicle. <br /><br />A device may have one or more values from the propulsion_type, depending on the number of modes of operation. For example, a scooter that can be powered by foot or by electric motor would have the propulsion_type represented by the array ['human', 'electric']. A bicycle with pedal-assist would have the propulsion_type represented by the array ['human', 'electric_assist'] if it can also be operated as a traditional bicycle. A car with an internal combustion engine would be represented by the array ['combustion']<br /><br />Current valid values are:<br /><ul><li>`human` _(Pedal or foot propulsion)_</li><li>`electric assist` _(Provides power only alongside human propulsion)_</li><li>`electric` _(Contains throttle mode with a battery-powered motor)_</li><li>`combustion` _(Contains throttle mode with a gas engine-powered motor)_</li></ul> This field was copied from [City of Los Angeles Mobility Data Specification](https://github.com/CityOfLosAngeles/mobility-data-specification/blob/73995a151f0a1d67aab3d617a4693f8f81967936/provider/README.md#propulsion-types)
+\- description | Optional | A free text description of the vehicle
+\- max_range | Optional | If the vehicle has a motor, this represents the furthest distance in meters that the vehicle can travel without recharging or refueling when it has the maximum amount of energy potential (for example a full battery or full tank of gas)
+
+Example:
+
+```json
+{
+  "last_updated": 1434054678,
+  "ttl": 0,
+  "data": {
+    "vehicle_types": [
+      {
+        "vehicle_type_id": "abc123",
+        "form_factor": "bicycle",
+        "propulsion_types": ["human"],
+        "description": "a bicycle without a motor"
+      },
+      {
+        "vehicle_type_id": "def456",
+        "form_factor": "scooter",
+        "propulsion_types": ["human", "electric"],
+        "description": "an electric scooter",
+        "max_range": 12345
+      }
+    ]
+  }
+}
+```
 
 ### station_information.json
 All stations contained in this list are considered public (ie, can be shown on a map for public use). If there are private stations (such as Capital Bikeshare’s White House station) these should not be exposed here and their status should not be included in station_status.json.
@@ -190,22 +229,90 @@ stations          | Yes       | Array that contains one object per station in th
 \- region_id       | Optional  | ID of the region where station is located (see [system_regions.json](#system_regionsjson))
 \- post_code       | Optional  | Postal code where station is located
 \- rental_methods  | Optional  | Array of enumerables containing the payment methods accepted at this station. <br />Current valid values (in CAPS) are:<br /><ul><li>KEY _(i.e. operator issued bike key / fob / card)_</li> <li>CREDITCARD</li> <li>PAYPASS</li> <li>APPLEPAY</li> <li>ANDROIDPAY</li> <li>TRANSITCARD</li> <li>ACCOUNTNUMBER</li> <li>PHONE</li> </ul> This list is intended to be as comprehensive at the time of publication as possible but is subject to change, as defined in [File Requirements](#file-requirements) above
-\- capacity        | Optional  | Number of total docking points installed at this station, both available and unavailable
+\- capacity        | Optional  | Number of total docking points installed at this station, both available and unavailable, regardless of what vehicle types are allowed at each dock. This field should only be used if every dock at the station is able to accept every vehicle type used in the system.
+\- vehicle_type_capacity        | Optional  | An object where each key is a vehicle_type_id as described in [vehicle_types.json](#vehicle_typesjson) and the value is a number representing the total docking points installed at this station, both available and unavailable for the specified vehicle type.
+
+Example:
+
+```json
+{
+  "last_updated": 1434054678,
+  "ttl": 0,
+  "data": {
+    "stations": [
+      {
+        "station_id": "pga",
+        "name": "Parking garage A",
+        "lat": 12.34,
+        "lon": 45.67,
+        "vehicle_type_capacity": {
+          "abc123": 7,
+          "def456": 9
+        }
+      }
+    ]
+  }
+}
+```
 
 ### station_status.json
 
 Field Name            | Required  | Defines
 --------------------- | ----------| ----------
 stations              | Yes       | Array that contains one object per station in the system as defined below
 \- station_id          | Yes       | Unique identifier of a station (see station_information.json)
-\- num_bikes_available | Yes       | Number of bikes available for rental
+\- num_bikes_available | Conditionally required       | Number of vehicles of all types available for rental. This field is not required if the `vehicles_available` field has been defined.
 \- num_bikes_disabled  | Optional  | Number of disabled bikes at the station. Vendors who do not want to publicize the number of disabled bikes or docks in their system can opt to omit station capacity (in station_information), num_bikes_disabled and num_docks_disabled. If station capacity is published then broken docks/bikes can be inferred (though not specifically whether the decreased capacity is a broken bike or dock)
-\- num_docks_available | Yes       | Number of docks accepting bike returns
+\- num_docks_available | Conditionally Required       | Number of docks accepting returns of any vehicle type. This field is not required if the `vehicle_docks_available` field has been defined. This field should only be used if every dock at the station is able to accept every vehicle type in the system
 \- num_docks_disabled  | Optional  | Number of empty but disabled dock points at the station. This value remains as part of the spec as it is possibly useful during development
 \- is_installed        | Yes       | 1/0 boolean - is the station currently on the street
 \- is_renting          | Yes       | 1/0 boolean - is the station currently renting bikes (even if the station is empty, if it is set to allow rentals this value should be 1)
 \- is_returning        | Yes       | 1/0 boolean - is the station accepting bike returns (if a station is full but would allow a return if it was not full then this value should be 1)
 \- last_reported       | Yes       | Integer POSIX timestamp indicating the last time this station reported its status to the backend
+\- vehicle_docks_available | Conditionally Required       | This field is required if the [vehicle_types.json](#vehicle_typesjson) file has been defined and the `num_docks_available` field is not defined. This field's value is an object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of docks accepting vehicle returns of vehicles of the respective vehicle type. If a single dock can accept multiple types, these should be added to the count of available docks for each applicable vehicle type.
+\- vehicle_docks_disabled  | Optional  | An object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of empty but disabled dock points for vehicles of the respective vehicle type at the station.
+\- vehicles_available | Conditionally Required       | This field is required if the [vehicle_types.json](#vehicle_typesjson) file has been defined. This field's value is an object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of vehicles of the respective vehicle type available for rental
+\- vehicles_disabled | Optional  | An object consisting of keys that are vehicle_type_ids as described in [vehicle_types.json](#vehicle_typesjson) and values that represent the number of disabled vehicles of the respective vehicle type at the station. Vendors who do not want to publicize the number of disabled vehicles or docks in their system can opt to omit station capacity (in station_information), num_vehicles_disabled and num_docks_disabled.
+
+Example:
+
+```json
+{
+  "last_updated": 1434054678,
+  "ttl": 0,
+  "data": {
+    "stations": [
+      {
+        "station_id": "station 1",
+        "is_installed": 1,
+        "is_renting": 1,
+        "is_returning": 1,
+        "last_reported": 1434054678,
+        "vehicles_available": {
+          "abc123": 3,
+          "def456": 4
+        },
+        "vehicle_docks_available": {
+          "abc123": 2,
+          "def456": 1
+        }
+      }, {
+        "station_id": "station 2",
+        "is_installed": 1,
+        "is_renting": 1,
+        "is_returning": 1,
+        "last_reported": 1434054678,
+        "num_docks_available": 8,
+        "vehicles_available": {
+          "abc123": 2,
+          "def456": 3
+        }
+      }
+    ]
+  }
+}
+```
+
 
 ### free_bike_status.json
 Describes bikes that are not at a station and are not currently in the middle of an active ride.
@@ -218,6 +325,38 @@ bikes             | Yes       | Array that contains one object per bike that is
 \- lon             | Yes       | Longitude of the bike. The field value must be a valid WGS 84 latitude in decimal degrees format. See: http://en.wikipedia.org/wiki/World_Geodetic_System, https://en.wikipedia.org/wiki/Decimal_degrees
 \- is_reserved     | Yes       | 1/0 value - is the bike currently reserved for someone else
 \- is_disabled     | Yes       | 1/0 value - is the bike currently disabled (broken)
+\- vehicle_type_id | Conditionally Required | The vehicle_type_id of this vehicle as described in [vehicle_types.json](#vehicle_typesjson). This field is required if the [vehicle_types.json](#vehicle_typesjson) is defined.
+\- range | Optional | If the vehicle has a motor, this value represents the furthest distance in meters that the vehicle can travel without recharging or refueling with the vehicle's current charge or fuel.
+
+Example:
+
+```json
+{
+  "last_updated": 1434054678,
+  "ttl": 0,
+  "data": {
+    "bikes": [
+      {
+        "bike_id": "ghi789",
+        "lat": 12.34,
+        "lon": 56.78,
+        "is_reserved": 0,
+        "is_disabled": 0,
+        "vehicle_type_id": "abc123"
+      }, {
+        "bike_id": "jkl012",
+        "lat": 12.34,
+        "lon": 56.78,
+        "is_reserved": 0,
+        "is_disabled": 0,
+        "vehicle_type_id": "def456",
+        "range": 450
+      }
+    ]
+  }
+}
+```
+
 
 ### system_hours.json
 Describes the system hours of operation. A JSON array of hours defined as follows:
@@ -325,9 +464,6 @@ There are some items that were proposed in an earlier version of this document b
     * _equipment_ - Removed due to a lack of specificity behind the intent of this field and a question about the actual relevance to the public
     * _jurisdictions_ - It is believed that the need for this field is negated by the presence of the system_regions.json feed
 
-* station_status.json
-    * need a way to distinguish between multiple bike types at a station if/when  hybrid systems using e-bikes become available
-
 ## Disclaimers
 
 _Apple Pay, PayPass and other third-party product and service names are trademarks or registered trademarks of their respective owners._