Skip to content

Commit

Permalink
Merge pull request #66 from MobilityData/isabelle-dr-patch-1
Browse files Browse the repository at this point in the history 
Update RULES.md
  • Loading branch information
@isabelle-dr
isabelle-dr committed Mar 16, 2022
2 parents 418409e + 00d0fe2 commit 35a2299
Showing 1 changed file with 42 additions and 42 deletions.
84 changes: 42 additions & 42 deletions RULES.md
View file
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">

0 comments on commit 35a2299

Please sign in to comment.