vehicles.json

{
  "$id": "https://raw.githubusercontent.com/openmobilityfoundation/mobility-data-specification/main/provider/vehicles.json",
  "$schema": "http://json-schema.org/draft-06/schema#",
  "title": "Schema for MDS Provider vehicles payloads",
  "type": "object",
  "definitions": {
    "string": {
      "$id": "#/definitions/string",
      "type": "string",
      "description": "A length-limited string type",
      "maxLength": 255,
      "default": "",
      "examples": [
        "ABC123"
      ],
      "pattern": "^(.*)$"
    },
    "timestamp": {
      "$id": "#/definitions/timestamp",
      "type": "number",
      "description": "Integer milliseconds since Unix epoch",
      "multipleOf": 1.0,
      "minimum": 0
    },
    "uuid": {
      "$id": "#/definitions/uuid",
      "type": "string",
      "description": "A UUID used to uniquely identifty an object",
      "default": "",
      "examples": [
        "3c9604d6-b5ee-11e8-96f8-529269fb1459"
      ],
      "pattern": "^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$"
    },
    "version": {
      "$id": "#/definitions/version",
      "type": "string",
      "description": "The version of MDS this data represents",
      "examples": [
        "1.0.0"
      ],
      "pattern": "^1\\.0\\.[0-9]+$"
    },
    "Point": {
      "$id": "#/definitions/Point",
      "title": "GeoJSON Point",
      "type": "object",
      "required": [
        "type",
        "coordinates"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "Point"
          ]
        },
        "coordinates": {
          "type": "array",
          "minItems": 2,
          "items": [
            {
              "type": "number",
              "minimum": -180.0,
              "maximum": 180.0
            },
            {
              "type": "number",
              "minimum": -90.0,
              "maximum": 90.0
            }
          ],
          "maxItems": 2
        },
        "bbox": {
          "type": "array",
          "minItems": 4,
          "items": {
            "type": "number"
          }
        }
      }
    },
    "MDS_Feature_Point": {
      "$id": "#/definitions/MDS_Feature_Point",
      "title": "MDS GeoJSON Feature Point",
      "type": "object",
      "required": [
        "type",
        "properties",
        "geometry"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "Feature"
          ]
        },
        "properties": {
          "type": "object",
          "required": [
            "timestamp"
          ],
          "properties": {
            "timestamp": {
              "$ref": "#/definitions/timestamp"
            },
            "stop_id": {
              "$ref": "#/definitions/uuid"
            }
          }
        },
        "geometry": {
          "$ref": "#/definitions/Point"
        },
        "bbox": {
          "type": "array",
          "minItems": 4,
          "items": {
            "type": "number"
          }
        }
      }
    },
    "links": {
      "$id": "#/definitions/links",
      "type": "object",
      "required": [
        "next"
      ],
      "properties": {
        "first": {
          "$id": "#/definitions/links/first",
          "type": [
            "null",
            "string"
          ],
          "title": "The URL to the first page of data",
          "examples": [
            "https://data.provider.co/trips/first"
          ],
          "format": "uri"
        },
        "last": {
          "$id": "#/definitions/links/last",
          "type": [
            "null",
            "string"
          ],
          "title": "The URL to the last page of data",
          "examples": [
            "https://data.provider.co/trips/last"
          ],
          "format": "uri"
        },
        "prev": {
          "$id": "#/definitions/links/prev",
          "type": [
            "null",
            "string"
          ],
          "title": "The URL to the previous page of data",
          "examples": [
            "https://data.provider.co/trips/prev"
          ],
          "format": "uri"
        },
        "next": {
          "$id": "#/definitions/links/next",
          "type": [
            "null",
            "string"
          ],
          "title": "The URL to the next page of data",
          "examples": [
            "https://data.provider.co/trips/next"
          ],
          "format": "uri",
          "pattern": "^(.*)$"
        }
      },
      "additionalProperties": false
    },
    "ttl": {
      "$id": "#/definitions/ttl",
      "type": "integer",
      "description": "Integer milliseconds until next data update (0 if the data is always refreshed)",
      "minimum": 0,
      "maximum": 300000
    },
    "vehicle_state": {
      "$id": "#/definitions/vehicle_state",
      "type": "string",
      "description": "The state of a vehicle",
      "enum": [
        "available",
        "elsewhere",
        "non_operational",
        "on_trip",
        "removed",
        "reserved",
        "unknown"
      ]
    },
    "vehicle_event": {
      "$id": "#/definitions/vehicle_event",
      "type": "string",
      "description": "An event that changes a vehicle's state",
      "enum": [
        "agency_drop_off",
        "agency_pick_up",
        "battery_charged",
        "battery_low",
        "comms_lost",
        "comms_restored",
        "compliance_pick_up",
        "decommissioned",
        "located",
        "maintenance",
        "maintenance_pick_up",
        "missing",
        "off_hours",
        "on_hours",
        "provider_drop_off",
        "rebalance_pick_up",
        "reservation_cancel",
        "reservation_start",
        "system_resume",
        "system_suspend",
        "trip_cancel",
        "trip_end",
        "trip_enter_jurisdiction",
        "trip_leave_jurisdiction",
        "trip_start",
        "unspecified"
      ]
    },
    "vehicle_events": {
      "$id": "#/definitions/vehicle_events",
      "type": "array",
      "description": "Array of events indicating a change to a vehicle's state",
      "uniqueItems": true,
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/vehicle_event"
      }
    },
    "propulsion_type": {
      "$id": "#/definitions/propulsion_type",
      "type": "string",
      "description": "The type of propulsion",
      "enum": [
        "combustion",
        "electric",
        "electric_assist",
        "human"
      ]
    },
    "propulsion_types": {
      "$id": "#/definitions/propulsion_types",
      "type": "array",
      "description": "Array of propulsion types, allowing multiple values",
      "items": {
        "$id": "#/definitions/propulsion_types/items",
        "$ref": "#/definitions/propulsion_type"
      },
      "uniqueItems": true
    },
    "vehicle_type": {
      "$id": "#/definitions/vehicle_type",
      "type": "string",
      "description": "The type of vehicle",
      "enum": [
        "bicycle",
        "car",
        "scooter",
        "moped",
        "other"
      ]
    }
  },
  "required": [
    "data",
    "version",
    "last_updated",
    "ttl"
  ],
  "properties": {
    "data": {
      "$id": "#/properties/data",
      "type": "object",
      "description": "The data records in this payload",
      "required": [
        "vehicles"
      ],
      "properties": {
        "vehicles": {
          "$id": "#/properties/data/properties/vehicles",
          "type": "array",
          "title": "The vehicles payload",
          "items": {
            "$id": "#/properties/data/properties/vehicles/items",
            "type": "object",
            "title": "The vehicle item schema",
            "required": [
              "provider_name",
              "provider_id",
              "device_id",
              "vehicle_id",
              "vehicle_type",
              "propulsion_types",
              "last_event_time",
              "last_vehicle_state",
              "last_event_types",
              "last_event_location"
            ],
            "properties": {
              "provider_name": {
                "$id": "#/definitions/vehicle/properties/provider_name",
                "$ref": "#/definitions/string",
                "description": "The public-facing name of the Provider"
              },
              "provider_id": {
                "$id": "#/definitions/vehicle/properties/provider_id",
                "$ref": "#/definitions/uuid",
                "description": "The UUID for the Provider, unique within MDS"
              },
              "device_id": {
                "$id": "#/definitions/vehicle/properties/device_id",
                "$ref": "#/definitions/uuid",
                "description": "A unique device ID in UUID format"
              },
              "vehicle_id": {
                "$id": "#/definitions/vehicle/properties/vehicle_id",
                "$ref": "#/definitions/string",
                "description": "The Vehicle Identification Number visible on the vehicle itself"
              },
              "vehicle_type": {
                "$id": "#/definitions/vehicle/properties/vehicle_type",
                "$ref": "#/definitions/vehicle_type",
                "description": "The type of vehicle"
              },
              "propulsion_types": {
                "$id": "#/definitions/vehicle/properties/propulsion_types",
                "$ref": "#/definitions/propulsion_types",
                "description": "The type of propulsion; allows multiple values",
                "minItems": 1
              },
              "last_event_time": {
                "$id": "#/properties/data/properties/vehicles/items/properties/last_event_time",
                "$ref": "#/definitions/timestamp",
                "description": "The time the most recent status change event occurred, expressed as a Unix Timestamp"
              },
              "last_vehicle_state": {
                "$id": "#/properties/data/properties/vehicles/items/properties/last_vehicle_state",
                "$ref": "#/definitions/vehicle_state",
                "description": "The last known state of the vehicle"
              },
              "last_event_types": {
                "$id": "#/properties/data/properties/vehicles/items/properties/last_event_types",
                "$ref": "#/definitions/vehicle_events",
                "description": "The most recent event(s) that caused a change in the vehicle's state"
              },
              "last_event_location": {
                "$id": "#/properties/data/properties/vehicles/items/properties/last_event_location",
                "$ref": "#/definitions/MDS_Feature_Point",
                "description": "Location of the vehicle's last status change event"
              },
              "current_location": {
                "$id": "#/properties/data/properties/vehicles/items/properties/current_location",
                "$ref": "#/definitions/MDS_Feature_Point",
                "description": "Current location of vehicle if different from last event, and the vehicle is not currently on a trip"
              },
              "battery_pct": {
                "$id": "#/properties/data/properties/vehicles/items/properties/battery_pct",
                "type": [
                  "number",
                  "null"
                ],
                "description": "Percent charge of device battery, expressed between 0 and 1",
                "examples": [
                  0.89
                ],
                "minimum": 0,
                "maximum": 1
              }
            },
            "allOf": [
              {
                "description": "Valid last_vehicle_state values for this endpoint",
                "properties": {
                  "last_vehicle_state": {
                    "enum": [
                      "available",
                      "non_operational",
                      "reserved"
                    ]
                  }
                }
              },
              {
                "description": "valid vehicle_state and vehicle_events combinations",
                "oneOf": [
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "available"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "agency_drop_off",
                            "battery_charged",
                            "comms_restored",
                            "located",
                            "maintenance",
                            "on_hours",
                            "provider_drop_off",
                            "reservation_cancel",
                            "system_resume",
                            "trip_cancel",
                            "trip_end",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "elsewhere"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "comms_restored",
                            "located",
                            "trip_leave_jurisdiction",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "non_operational"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "battery_low",
                            "comms_restored",
                            "located",
                            "maintenance",
                            "off_hours",
                            "system_suspend",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "on_trip"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "comms_restored",
                            "located",
                            "trip_enter_jurisdiction",
                            "trip_start",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "removed"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "agency_pick_up",
                            "compliance_pick_up",
                            "decommissioned",
                            "located",
                            "maintenance_pick_up",
                            "rebalance_pick_up",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "reserved"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "comms_restored",
                            "located",
                            "reservation_start",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  },
                  {
                    "properties": {
                      "last_vehicle_state": {
                        "const": "unknown"
                      },
                      "last_event_types": {
                        "contains": {
                          "enum": [
                            "comms_lost",
                            "missing",
                            "unspecified"
                          ]
                        }
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "additionalProperties": false
    },
    "version": {
      "$id": "#/properties/version",
      "$ref": "#/definitions/version"
    },
    "links": {
      "$id": "#/properties/links",
      "$ref": "#/definitions/links"
    },
    "last_updated": {
      "$id": "#/properties/last_updated",
      "$ref": "#/definitions/timestamp"
    },
    "ttl": {
      "$id": "#/properties/ttl",
      "$ref": "#/definitions/ttl"
    }
  },
  "additionalProperties": false
}