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

  • description : Vehicle description.

  • 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.

  • 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.

  • 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.

  • mileageFromOdometer : The total distance travelled by the particular vehicle since its initial production, as read from its odometer.

  • vehicleConfiguration : A short text indicating the configuration of the vehicle, e.g. '5dr hatchback ST 2.5 MT 225 hp' or 'limited edition'.

  • color : Vehicle's color.

  • owner : Vehicle's owner.

  • 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.

  • 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.
    • 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