Vehicle

Description

A vehicle.

Data Model

The data model is defined as shown below:

id : Entity's unique identifier.
type : Entity type. It must be equal to Vehicle.
source : A sequence of characters giving the source of the entity data.
- Attribute type: Property. Text or URL
- Optional
dataProvider : Specifies the URL to information about the provider of this information
- Attribute type: Property. URL
- Optional
name : Name given to this vehicle
- Normative References: https://schema.org/name
- Optional
- Attribute type: Property. Text or URL
- Optional
description : Vehicle description.
- Normative References: https://schema.org/description
- Optional
vehicleType : Type of vehicle from the point of view of its structural characteristics. This is different than the vehicle category (see below).
- Attribute type: Property. Text
- Allowed Values: The following values defined by VehicleTypeEnum and VehicleTypeEnum2, DATEX 2 version 2.3:
  - (agriculturalVehicle, bicycle, bus, minibus, car, caravan, tram, tanker, carWithCaravan, carWithTrailer, lorry, moped, tanker, motorcycle, motorcycleWithSideCar, motorscooter, trailer, van, caravan, constructionOrMaintenanceVehicle)
  - (trolley, binTrolley, sweepingMachine, cleaningTrolley)
- Mandatory
category : Vehicle category(ies) from an external point of view. This is different than the vehicle type (car, lorry, etc.) represented by the vehicleType property.
- Attribute type: Property. List of Text
- Allowed values:
  - (public, private, municipalServices, specialUsage).
  - (tracked, nonTracked). Tracked vehicles are those vehicles which position is permanently tracked by a remote system.
  - Or any other needed by an application They incorporate a GPS receiver together with a network connection to periodically update a reported position (location, speed, heading ...).
- Mandatory
location : Vehicle's last known location represented by a GeoJSON Point. Such point may contain the vehicle's altitude as the third component of the coordinates array.
- Attribute type: GeoProperty. geo:json.
- Normative References: https://tools.ietf.org/html/rfc7946
- Attribute metadata:
  - timestamp: Timestamp which captures when the vehicle was at that location. This value can also appear as a FIWARE TimeInstant
  - Type: DateTime or ISO8601 (legacy).
  - Mandatory
- Mandatory only if category contains tracked.
previousLocation : Vehicle's previous location represented by a GeoJSON Point. Such point may contain the previous vehicle's altitude as the third component of thecoordinates array.
- Attribute type: Property. geo:json.
- Normative References:
- Attribute metadata:
  - timestamp: Timestamp which captures when the vehicle was at that location.
  - Type: DateTime
  - Mandatory
- Optional
speed : Denotes the magnitude of the horizontal component of the vehicle's current velocity and is specified in Kilometers per Hour. If provided, the value of the speed attribute must be a non-negative real number. -1 MAY be used if speed is transiently unknown for some reason.
- Attribute type: Property. Number
- Default unit: Kilometers per hour
- Attribute metadata:
  - timestamp : Timestamp which captures when the vehicle was moving at that speed. This value can also appear as a FIWARE TimeInstant
  - Type: DateTime or ISO8601 (legacy).
  - Mandatory
- Mandatory only if category contains tracked.
heading : Denotes the direction of travel of the vehicle and is specified in decimal degrees, where 0° ≤ heading < 360°, counting clockwise relative to the true north. If the vehicle is stationary (i.e. the value of the speed attribute is 0), then the value of the heading attribute must be equal to -1.
- Attribute type: Property. Number
- Attribute metadata:
  - timestamp : Timestamp which captures when the vehicle was heading towards such direction. This value can also appear as a FIWARE TimeInstant
  - Type: DateTime or ISO8601 (legacy).
  - Mandatory
- Mandatory only if category contains tracked.
cargoWeight : Current weight of the vehicle's cargo.
- Attribute type: Property. Number
- Attribute metadata:
  - timestamp: Timestamp associated to this measurement. This value can also appear as a FIWARE TimeInstant
    - Type: DateTime or ISO8601 (legacy).
    - Mandatory
- Default unit: Kilograms
- Optional
vehicleIdentificationNumber : The Vehicle Identification Number (VIN) is a unique serial number used by the automotive industry to identify individual motor vehicles.
- Normative References: https://schema.org/vehicleIdentificationNumber
- Mandatory if neither vehiclePlateIdentifier nor fleetVehicleId is defined.
vehiclePlateIdentifier : An identifier or code displayed on a vehicle registration plate attached to the vehicle used for official identification purposes. The registration identifier is numeric or alphanumeric and is unique within the issuing authority's region.
- Normative References: DATEXII vehicleRegistrationPlateIdentifier
- Attribute Type: Text
- Mandatory if neither vehicleIdentificationNumber nor fleetVehicleId is defined.
fleetVehicleId : The identifier of the vehicle in the context of the fleet of vehicles to which it belongs.
- Attribute Type: Text
- Mandatory if neither vehiclePlateIdentifier nor vehicleIdentificationNumber is defined.
dateVehicleFirstRegistered : The date of the first registration of the vehicle with the respective public authorities.
- Normative References: https://schema.org/dateVehicleFirstRegistered
- Optional
dateFirstUsed : Timestamp which denotes when the vehicle was first used.
- Attribute type: Property. DateTime
- Optional
purchaseDate : The date the item e.g. vehicle was purchased by the current owner.
- Normative References: https://schema.org/purchaseDate
- Optional
mileageFromOdometer : The total distance travelled by the particular vehicle since its initial production, as read from its odometer.
- Normative References: https://schema.org/mileageFromOdometer
- Attribute metadata:
  - timestamp: Timestamp associated to this measurement. This value can also appear as a FIWARE TimeInstant
    - Type: DateTime or ISO8601 (legacy).
    - Mandatory
- Optional
vehicleConfiguration : A short text indicating the configuration of the vehicle, e.g. '5dr hatchback ST 2.5 MT 225 hp' or 'limited edition'.
- Normative References: https://schema.org/vehicleConfiguration
- Optional
color : Vehicle's color.
- Normative References: https://schema.org/color
- Optional
owner : Vehicle's owner.
- Attribute Type: list of references to entities of type https://schema.org/Person or https://schema.org/Organization or List of URIs
- Optional
feature : Feature(s) incorporated by the vehicle.
- Attribute type: Property. List of Text
- Allowed values: (gps, airbag, overspeed, abs, wifi, backCamera, proximitySensor, disabledRamp, alarm, internetConnection) or any other needed by the application.
  - In order to represent multiple instances of a feature it can be used the following syntax: "<feature>,<occurences>". For example, a car with 4 airbags will be represented by "airbag,4".
- Optional
serviceProvided : Service(s) the vehicle is capable of providing or it is assigned to.
- Attribute type: Property. List of Text
- Allowed values: (garbageCollection, parksAndGardens, construction, streetLighting, roadSignalling, cargoTransport, urbanTransit, maintenance, streetCleaning, wasteContainerCleaning, auxiliaryServices goodsSelling, fairground, specialTransport) or any other value needed by an specific application.
- Optional
vehicleSpecialUsage : Indicates whether the vehicle is been used for special purposes, like commercial rental, driving school, or as a taxi. The legislation in many countries requires this information to be revealed when offering a car for sale.
- Normative References: https://auto.schema.org/vehicleSpecialUsage
- Allowed values: (taxi, ambulance, police, fireBrigade, schoolTransportation, military)
- Optional
refVehicleModel : Vehicle's model.
- Attribute type: Property. Reference to a VehicleModel entity.
- Optional
areaServed : Higher level area served by this vehicle. It can be used to group vehicles per responsible, district, neighbourhood, etc.
- Attribute type: Property. Text
- Optional
serviceStatus : Vehicle status (from the point of view of the service provided, so it could not apply to private vehicles).
- Allowed values:
  - parked : Vehicle is parked and not providing any service at the moment.
  - onRoute : Vehicle is performing a mission. A comma-separated modifier(s) can be added to indicate what mission is currently delivering the vehicle. For instance "onRoute,garbageCollection" can be used to denote that the vehicle is on route and in a garbage collection mission.
  - broken : Vehicle is suffering a temporary breakdown.
  - outOfService : Vehicle is on the road but not performing any mission, probably going to its parking area.
- Attribute type: Property. Text
- Attribute metadata:
  - timestamp : Timestamp which reflects when the referred service status was captured.
    - Type: DateTime
    - Mandatory
- Optional
dateModified : Last update timestamp of this entity.
- Attribute type: Property. DateTime
- Read-Only. Automatically generated.
dateCreated : Creation timestamp of this entity.
- Attribute type: Property. DateTime
- Read-Only. Automatically generated.

Note: JSON Schemas are intended to capture the data type and associated constraints of the different Attributes, regardless their final representation format in NGSI(v2, LD).

Examples

Normalized Example

Normalized NGSI response

{
    "id": "vehicle:WasteManagement:1",
    "type": "Vehicle",
    "category": {
        "value": ["municipalServices"]
    },
    "vehicleType": {
        "value": "lorry"
    },
    "name": {
        "value": "C Recogida 1"
    },
    "vehiclePlateIdentifier": {
        "value": "3456ABC"
    },
    "refVehicleModel": {
        "type": "Relationship",
        "value": "vehiclemodel:econic"
    },
    "location": {
        "type": "geo:json",
        "value": {
            "type": "Point",
            "coordinates": [-3.164485591715449, 40.62785133667262]
        },
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2018-09-27T12:00:00"
            }
        }
    },
    "areaServed": {
        "value": "Centro"
    },
    "serviceStatus": {
        "value": "onRoute"
    },
    "cargoWeight": {
        "value": 314
    },
    "speed": {
        "value": 50,
        "metadata": {
            "timestamp": {
                "type": "DateTime",
                "value": "2018-09-27T12:00:00"
            }
        }
    },
    "serviceProvided": {
        "value": ["garbageCollection", "wasteContainerCleaning"]
    }
}

key-value pairs Example

Sample uses simplified representation for data consumers ?options=keyValues

{
    "id": "vehicle:WasteManagement:1",
    "type": "Vehicle",
    "vehicleType": "lorry",
    "category": ["municipalServices"],
    "location": {
        "type": "Point",
        "coordinates": [-3.164485591715449, 40.62785133667262]
    },
    "name": "C Recogida 1",
    "speed": 50,
    "cargoWeight": 314,
    "serviceStatus": "onRoute",
    "serviceProvided": ["garbageCollection", "wasteContainerCleaning"],
    "areaServed": "Centro",
    "refVehicleModel": "vehiclemodel:econic",
    "vehiclePlateIdentifier": "3456ABC"
}

LD Example

Sample uses the NGSI-LD representation

{
    "id": "urn:ngsi-ld:Vehicle:vehicle:WasteManagement:1",
    "type": "Vehicle",
    "category": {
        "type": "Property",
        "value": ["municipalServices"]
    },
    "vehicleType": {
        "type": "Property",
        "value": "lorry"
    },
    "name": {
        "type": "Property",
        "value": "C Recogida 1"
    },
    "vehiclePlateIdentifier": {
        "type": "Property",
        "value": "3456ABC"
    },
    "refVehicleModel": {
        "type": "Relationship",
        "object": "urn:ngsi-ld:VehicleModel:vehiclemodel:econic"
    },
    "location": {
        "type": "GeoProperty",
        "value": {
            "type": "Point",
            "coordinates": [-3.164485591715449, 40.62785133667262]
        },
        "observedAt": "2018-09-27T12:00:00Z"
    },
    "areaServed": {
        "type": "Property",
        "value": "Centro"
    },
    "serviceStatus": {
        "type": "Property",
        "value": "onRoute"
    },
    "cargoWeight": {
        "type": "Property",
        "value": 314
    },
    "speed": {
        "type": "Property",
        "value": 50,
        "observedAt": "2018-09-27T12:00:00Z"
    },
    "serviceProvided": {
        "type": "Property",
        "value": ["gargabeCollection", "wasteContainerCleaning"]
    },
    "@context": [
        "https://uri.etsi.org/ngsi-ld/v1/ngsi-ld-core-context.jsonld",
        "https://schema.lab.fiware.org/ld/context"
    ]
}

Test it with a real service

T.B.D.

Issues

Taxonomy of service types
Vehicle special usage categories as defined by different countries have not been clarified