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

Update RULES.md #66

Merged
merged 1 commit into from
Mar 16, 2022
Merged

Update RULES.md #66

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
84 changes: 42 additions & 42 deletions RULES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,41 +1,38 @@
This project validates feeds up to version 2.3-RC of the [JSON Schemas](https://github.com/MobilityData/gbfs-json-schema).
# Files presence
The validator will display a message for all files that are present. A message will be displayed for each missing file. See examples below.
The validator will flag any missing file. It will inform the user if the missing file is required or not, as per the conditions in the GBFS version that it detects.

Missing file but not required:

<img width="800" alt="tick boxes" src="https://user-images.githubusercontent.com/63653518/133173202-459fc2e3-6c4b-4748-8a37-94ed362210c0.png">

Missing file and required:

<img width="800" alt="tick boxes" src="https://user-images.githubusercontent.com/63653518/133173256-d57d5b5a-4eb0-4114-89a6-fac60b3864a1.png">
<img width="600" alt="Screen Shot 2022-03-01 at 10 10 07 AM" src="https://user-images.githubusercontent.com/63653518/156194659-afcc64ef-1e57-4d60-b8c1-2daebf1ef2bd.png">

## Required files
system_information.json is required for all GBFS versions.
gbfs.json is required as of v2.0
`system_information.json` is **required** for all GBFS versions.
`gbfs.json` is required as of v2.0

## Conditionally required files
Three files are conditionally required for all GBFS versions:
station_information.json: required for systems utilizing docks
station_status.json: required for systems utilizing docks
free_bike_status.json: required for free floating vehicles
The validator will check for the presence of those files depending on the options “Free-floating” or Docked” that the user selected on the interface.
Three files are **conditionally required** for all GBFS versions:
- `station_information.json`: required for systems utilizing docks
- `station_status.json`: required for systems utilizing docks
- `free_bike_status.json`: required for free floating vehicles
The validator will check for the presence of the files depending on the options “Free-floating” or Docked” that the user selected on the interface.

<img width="350" alt="tick boxes" src="https://user-images.githubusercontent.com/63653518/156194900-bab75f85-f681-43a4-84d3-08c9d6fed4df.png">

<img width="350" alt="tick boxes" src="https://user-images.githubusercontent.com/63653518/133173329-fab3967d-5e4c-459f-bd2f-ec3415b98d44.png">

One additional conditionally required file has been added in GBFS version 2.1:
vehicle_types.json
The validator is currently considering this file as not required, because the conditions are more complex and can’t be represented by the schema currently.
The Validator also checks the conditional requirement of the file `vehicle_types.json`: as per the [official GBFS specification](https://github.com/NABSA/gbfs/blob/master/gbfs.md#vehicle_typesjson), it is required of systems that include information about vehicle types in the `vehicle_status.json file`.

# Fields presence and types

# Fields presence and field types
## Required fields
Each file has to be structured in a specific output format. The fields `last_updated`, `ttl`, `version`, `data` are required and checked by the validator.
In “data”, there is a nested JSON containing all the fields mentioned in the specification. All the fields that are described as “required” will be checked by the validator.
Some fields are required only if the parent field is defined, and this is considered a conditionally required field.
Each file in GBFS has to be structured in a specific [output format](https://github.com/NABSA/gbfs/blob/master/gbfs.md#output-format).
All the fields that are described as **required** in GBFS will be checked by the validator.
Some fields are required only if the parent field is defined, and this is considered a **conditionally required** field.

## Conditionally Required fields
This validator checks the simple "conditionally required" fields that are represented in the JSON Schemas. The following conditions are covered:
- system_information.json
The simple **conditionally required** fields (where the condition depends on another field in the same file) are represented by the JSON Schemas and will be checked by this validator.\
The more complex **conditionally required fields** are covered by custom rules that have been added in this validator (in [PR#63](https://github.com/MobilityData/gbfs-validator/pull/63)).\

The following conditions are all covered by this validator:
- **system_information.json**

`brand_assets.brand_last_modified`\
`brand_assets.brand_image_url`\
Expand All @@ -46,28 +43,38 @@ This validator checks the simple "conditionally required" fields that are repres
`rental_apps.ios.store_uri`\
`rental_apps.ios.discovery_uri`


- vehicle_types.json
- **vehicle_types.json**

`vehicle_types.max_range_meters`\
`vehicle_types.vehicle_assets.icon_url`\
`vehicle_types.vehicle_assets.icon_last_modified`
`vehicle_types.vehicle_assets.icon_last_modified`\
`default_pricing_plan_id`

- station_status.json
- **station_status.json**

`stations.vehicle_types_available.vehicle_type_id`\
`stations.vehicle_types_available.count`\
`stations.vehicle_docks_available.vehicle_type_ids`\
`stations.vehicle_docks_available.count`
`stations.vehicle_docks_available.count`\
`vehicle_types_available`

- geofencing_zones.json
- **geofencing_zones.json**

`geofencing_zones.features.properties.rules.ride_allowed`\
`geofencing_zones.features.properties.rules.ride_through_allowed`

- **free_bike_status.json**
`vehicle_type_id`
`current_range_meters`

- **conditions that are not covered by this validator**
`num_docks_available` in station_status.json`: because it depends on something that isn't defined in the GBFS files: the docking capacity. See the official GBFS spec about this field [here](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson).\
`vehicle_docks_available` in station_status.json`: because it depends on something that isn't defined in the GBFS files: *REQUIRED in feeds where [...] certain docks are only able to accept certain vehicle types.* See the official GBFS spec about this field [here](https://github.com/NABSA/gbfs/blob/master/gbfs.md#station_statusjson).\
`system_id` in `free_bike_status.json`

## Field types
Each field has a specific field type, as described in the specification.
The validators will flag the following field type if they are invalid, as they are present in the JSON Schema:
The validators will flag the following field type if they are invalid.
- array
- boolean
- date: defined in regex using the formula ```^[0-9]{4}-[0-9]{2}-[0-9]{2}$```
Expand All @@ -85,16 +92,9 @@ The validators will flag the following field type if they are invalid, as they a
- timestamp: Defined as integer, with minimum set to Tuesday, December 15, 2015 5:00:00 AM (when GBFS was created)
- url

See examples for wrong field types below

Wrong enum value:
![missing enum](https://user-images.githubusercontent.com/63653518/133173526-7d031fd3-30fb-412c-be9a-4a1dc4d6ae23.png)

Wrong field type:
![wrong type](https://user-images.githubusercontent.com/63653518/133173621-0043bc10-cf21-4502-8c09-b4fc5fd3e9c6.png)



See examples for wrong field types below:


<img width="800" alt="enum" src="https://user-images.githubusercontent.com/63653518/156201396-af4e7372-732a-43e4-b7da-0d6efa37df53.png">
<img width="800" alt="type" src="https://user-images.githubusercontent.com/63653518/156201428-27ffa407-a951-4f1d-bc2c-d82eecc2fe2d.png">