Clarify Source, Sensor, Provider fields in Events

[schnuerle]

There are a number of fields that serve similar but distinct purposes in the Events API. These need some more thought and clarification so people reading the spec can understand their differences and when to use them.

https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/events/README.md#curb-event

Name	Type	Required/Optional	Description
source_operator_id	UUID	Required	Unique identifier of the entity responsible for operating the event source.
source_id	UUID	Required	Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded.
provider_id	UUID	Optional	Unique ID of the provider responsible for operating the vehicle at the time of the event, if any. IDs are global and come from the providers.csv file here in the CDS repo.
provider_name	String	Optional	Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event, if any.
sensor_id	UUID	Optional	If a sensor was used, the globally unique identifier of the sensor that recorded the event.
source_type	Enum Source Type	Required	General category of the source creating the event.

[schnuerle]

Added source_type as a new field
https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/events/README.md#source-type

[schnuerle]

From conversation with Jascha, list could be simplified to:

data_source_type: General descriptor of the source by which the event data was derived
data_source_device_id : Device id that captured the data
data_source_organization_name : text of the name of the organization providing the device
data_source_organization_id : globally registered UUID of the organization providing the device, if company data feed
vehicle_fleet_name : owner of the vehicle who is using the curb

Note in MDS both org name and id are provided.

Could also have data_source_attributes which has sensor-specific field:value pairs for any unique data specific to a source (eg, confidence interval, etc).

[schnuerle]

Should we use data_source_operator_id and data_source_operator_name instead, to be more specific?

[schnuerle]

Reworked many of these field names based on the WG and WGSC and OMF Staff discussions to help group field names with prefixes, clarify purpose, merge redundant fields, and add/rearrange some other fields.

You can see the result in the spec here: https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/events/README.md#curb-event

I feel that the 'providers.csv' file, which is how it's named in MDS, is not appropriately named here in CDS, since we are not talking about Mobility Service Providers, and instead about the operators of the data source (e.g. company fleet owner, third party sensor operator, city monitor, etc). So this could be renamed 'operators.csv' to make it clear it's a global catalog of data source operators.

Here is the new object table for reference (formatting is not very good here in a comment):

Name	Type	Required/Optional	Description
event_id	UUID	Required	The globally unique identifier of the event that occurred.
event_type	Event Type	Required	The event_type that happened for this event.
event_purpose	Event Purpose	Conditionally Required	General curb usage purpose that the vehicle performed during the event. Required for sources capable of determining activity type for relevant event_types.
event_location	GeoJSON	Required	The geographic point location where the event occurred.
event_time	Timestamp	Required	Time at which the event occurred.
event_publication_time	Timestamp	Required	Time at which the event became available for consumption by this API.
curb_zone_id	UUID	Conditionally Required	Unique ID of the Curb Zone where the event occurred. Required for events that occurred at a known Curb Zone for ALL event_types.
curb_area_ids	UUID	Conditionally Required	Unique IDs of the Curb Area where the event occurred. Since Curb Areas can overlap, an event may happen in more than one. Required for events that occurred in a known Curb Area for these event_types: enter_area, exit_area, park_start, park_end
curb_space_id	UUID	Conditionally Required	Unique ID of the Curb Space where the event occurred. Required for events that occurred at a known Curb Space for these event_types: park_start, park_end, enter_area, exit_area
data_source_type	Enum Source Type	Required	General category of the source creating the event.
data_source_operator_id	UUID	Conditionally Required	Unique identifier of the entity responsible for operating the event data source. IDs can identify the fleet operator sending a data feed, the organization (company or city) operating the sensor. IDs for fleet operators are required and global and come from the providers.csv file, and optional for others. Read our How to Get a Provider ID guide. An agency at their discretion may allow a small, local company to simply provide a consistent data_source_operator_name string instead of this field.
data_source_operator_name	String	Optional	Name of the provider responsible for operating the vehicle, device, or sensor at the time of the event. May be sent along with data_source_operator_id or on its own for small operators at the discretion of the city.
data_source_device_id	UUID	Required	Unique identifier of this event source, whether sensor, vehicle, camera, etc. Allows agencies to connect related Events as they are recorded by the same source. If coming from a provider, this is a generated UUID they use and not the same as the external vehicle_id.
data_source_manufacturer	String	Optional	Manufacturer of the data source hardware or vehicle reporting event data.
data_source_model	String	Optional	Model of the data source hardware or vehicle reporting event data.
sensor_status_is_commissioned	Boolean	Optional	If a sensor was used to capture this event, the commissioned status at the time that the event was reported. Indicates whether the sensor is currently in a state where it should be reporting data.
sensor_status_is_online	Boolean	Optional	If a sensor was used to capture this event, the online status at the time that the event was reported. Indicates whether the sensor is currently online and reporting data.
vehicle_id	String	Optional	A vehicle identifier visible externally on the vehicle itself.
vehicle_license_plate	String	Optional	The consistently placed vehicle license plate, usable by ALPR systems, when required for curb use. This field is potentially sensitive (depending on local, state, and national laws) and a data privacy framework is recommended for collecting, retention, deletion, obfuscation, and security.
vehicle_permit_number	String	Optional	If applicable, the assigned permit number for this vehicle from the city agency.
vehicle_length	Integer	Conditionally Required	Approximate length of the vehicle that performed the event, in centimeters. Required for sources capable of determining vehicle length.
vehicle_type	Vehicle Type	Conditionally Required	Type of the vehicle that performed the event. Required for sources capable of determining vehicle type.
vehicle_propulsion_types	Array of Propulsion Type	Conditionally Required	List of propulsion types used by the vehicle that performed the event. Required for sources capable of determining vehicle propulsion type.
vehicle_blocked_lane_types	Array of Lane Type	Conditionally Required	Type(s) of lane blocked by the vehicle performing the event. If no lanes are blocked by the vehicle performing the event, the array should be empty. Required for the following event_types: park_start
curb_occupants	Array of Curb Occupant	Conditionally Required	Current occupants of the Curb Zone. If the sensor is capable of identifying the linear location of the vehicle, then elements are sorted in ascending order according to the start property of the linear reference. Otherwise, elements appear in no particular order. Required for the following event_types: park_start, park_end, scheduled_report
currency	String	Optional	Fields specifying a monetary cost use a currency as specified in ISO 4217. All costs should be given as integers in the currency's smallest unit. As an example, to represent $1 USD, specify an amount of 100 (for 100 cents). If the currency field is null, USD cents is implied.
actual_cost	Integer	Optional	If available from the source, the actual cost, in the currency defined in currency, paid by the curb user for this event.

[schnuerle]

Pulling this thought out into its own comment for discussion:

I feel that the 'providers.csv' file, which is how it's named in MDS, is not appropriately named here in CDS, since we are not talking about Mobility Service Providers, and instead about the operators of the data source (e.g. company fleet owner, third party sensor operator, city monitor, etc). So this could be renamed 'operators.csv' to make it clear it's a global catalog of data source operators.

The WGSC discussed naming this file 'data_source_operators.csv' to maintain direct consistency and clarity of connection with the data_source_operator_id field name.

I don't think we have to maintain consistency with MDS here and the use of the term 'providers' since it reduces people's understanding of the point of the field and file in CDS.

[schnuerle]

After talking to staff and WGSC, we've agreed to make it clear what this file is for: anyone operating a data source and returning CDS data for an agency. To that end the file has been renamed, Events and Curbs updated, and the guidance document renamed and updated.