Merge pull request #778 from OpenSimulationInterface/750-define-mandatory-field-with-checker-rules

Define mandatory field with checker rules

Author: pmai

doc/architecture/architecture_overview.adoc

@@ -51,7 +51,8 @@ This has been done to allow backward-compatible changes in the field.
 Additionally, this is the default behavior in Protocol Buffer version 3 that no longer has the `required` type.
 Setting all fields to `optional` thus ensures update compatibility.
 However, this does not mean that it is optional to fill the field.
-For the purpose of providing a complete interface, all existing fields should be set, unless not setting a field carries a specific meaning, as indicated in the accompanying comment.
+Fields with the rule `is_set` are mandatory and have to be set at all times.
+All other fields have to be set according to the requirements of the connected models.
 
 NOTE: All field numbers equal to or greater than 10000 are available for user-specific extensions via custom fields.
 No future evolution of OSI will therefore use field numbers equal to or greater than 10000.

osi_detectedobject.proto

@@ -17,6 +17,10 @@ message DetectedItemHeader
     // Specific ID of the detected item as assigned by the sensor internally.
     // Needs not to match with \c #ground_truth_id.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier tracking_id = 1;
 
     // The ID of the original detected item in the ground truth.

osi_featuredata.proto

@@ -92,6 +92,10 @@ message SensorDetectionHeader
     // \par Reference:
     // [1] DIN Deutsches Institut fuer Normung e. V. (2013). <em>DIN ISO 8855 Strassenfahrzeuge - Fahrzeugdynamik und Fahrverhalten - Begriffe</em>. (DIN ISO 8855:2013-11). Berlin, Germany.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional MountingPosition mounting_position = 3;
 
     // The origin/orientation of the sensor frame represents the current
@@ -124,6 +128,10 @@ message SensorDetectionHeader
     // This ID can equal \c SensorData::sensor_id, if \c SensorData holds only
     // data from one sensor/sensor model.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier sensor_id = 7;
 
     // The extended qualifier describes the reason (not the effect) why the

osi_groundtruth.proto

@@ -47,6 +47,10 @@ message GroundTruth
     // The interface version used by the sender (i.e. the simulation
     // environment).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp of the simulation environment. The zero time point is
@@ -60,6 +64,10 @@ message GroundTruth
     // (there is no inherent latency for ground truth data, as opposed to
     // sensor data).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The ID of the host vehicle object referencing to \c MovingObject .
@@ -68,6 +76,7 @@ message GroundTruth
     //
     // \rules
     // refers_to: MovingObject
+    // is_set
     // \endrules
     //
     optional Identifier host_vehicle_id = 3;
@@ -118,7 +127,7 @@ message GroundTruth
     // [1] ISO International Organization for Standardization. (2013). <em>ISO 3166-1 Codes for the representation of names of countries and their subdivisions - Part 1: Country codes</em>. (ISO 3166-1:2013). Geneva, Switzerland.
     //
     // \rules
-    // is_iso_country_code:
+    // is_iso_country_code
     // \endrules
     //
     optional uint32 country_code = 13;

osi_lane.proto

@@ -42,6 +42,7 @@ message Lane
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;

osi_logicaldetectiondata.proto

@@ -19,6 +19,10 @@ message LogicalDetectionData
     // The interface version used by the sender (i.e. the simulation
     // environment).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // Header attributes of fused detections from multiple sensors and sensor types.

osi_logicallane.proto

@@ -56,6 +56,7 @@ message LogicalLaneBoundary
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;

osi_motionrequest.proto

@@ -25,11 +25,19 @@ message MotionRequest
 {
     // The interface version used by the sender (simulation environment).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp of the simulation environment.
     // A reference to \c Timestamp message.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // Define the type that is used to specify the motion request.

osi_object.proto

@@ -21,6 +21,7 @@ message StationaryObject
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;
@@ -388,6 +389,7 @@ message MovingObject
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;

osi_referenceline.proto

@@ -32,6 +32,7 @@ message ReferenceLine
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;

osi_roadmarking.proto

@@ -29,6 +29,10 @@ message RoadMarking
 {
     // The ID of the road marking.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier id = 1;
 
     // The base parameters of the road marking.

osi_route.proto

@@ -40,6 +40,10 @@ message Route
     // \note This id must be unique within all route messages exchanged with
     // one traffic participant.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier route_id = 1;
 
     // Route segments that form the route of an agent.

osi_sensordata.proto

@@ -102,6 +102,10 @@ message SensorData
 {
     // The interface version used by the sender.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The timestamp of the sensor data. Zero time is arbitrary but must be
@@ -129,6 +133,10 @@ message SensorData
     // a dumb sensor with no internal time concept), the two timestamps might
     // also be identical, but delayed from the \c GroundTruth timestamp.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The sensors estimated location of the host vehicle
@@ -156,6 +164,10 @@ message SensorData
     // object output; it is distinct from the IDs of its physical detectors,
     // which are used in the detected features.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier sensor_id = 5;
 
     // The virtual mounting position of the sensor (origin and orientation
@@ -186,6 +198,10 @@ message SensorData
     // vehicle's bounding box \c MovingObject::base . \c
     // BaseMoving::orientation.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional MountingPosition mounting_position = 6;
 
     // The root mean squared error of the mounting position.

osi_sensorview.proto

@@ -36,6 +36,10 @@ message SensorView
 {
     // The interface version used by the sender (simulation environment).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp of the simulation environment. Zero time is arbitrary
@@ -48,6 +52,10 @@ message SensorView
     // (there is no inherent latency for sensor view data, as opposed to
     // sensor data).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The ID of the sensor at host vehicle's \c #mounting_position.
@@ -58,6 +66,7 @@ message SensorView
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier sensor_id = 3;
@@ -92,6 +101,10 @@ message SensorView
     // vehicle's bounding box \c MovingObject::base . \c
     // BaseMoving::orientation.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional MountingPosition mounting_position = 4;
 
     // The root mean squared error of the mounting position.
@@ -127,6 +140,7 @@ message SensorView
     //
     // \rules
     // refers_to: 'MovingObject'
+    // is_set
     // \endrules
     //
     optional Identifier host_vehicle_id = 8;

osi_sensorviewconfiguration.proto

@@ -66,6 +66,10 @@ message SensorViewConfiguration
 {
     // The interface version used by the sender (simulation environment).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The ID of the sensor at host vehicle's mounting_position.
@@ -77,6 +81,10 @@ message SensorViewConfiguration
     // The ID is to be provided by the environment simulation, the sensor
     // model is not in a position to provide a useful default value.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier sensor_id = 2;
 
     // The virtual mounting position of the sensor (origin and orientation

osi_streamingupdate.proto

@@ -30,6 +30,10 @@ message StreamingUpdate
 {
     // The interface version used by the sender.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp where the information of contained objects is calculated. 
@@ -38,6 +42,10 @@ message StreamingUpdate
     // Zero time does not need to coincide with the UNIX epoch. 
     // Recommended is the starting time point of the simulation.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The list of stationary objects (excluding traffic signs and traffic

osi_trafficcommand.proto

@@ -21,6 +21,10 @@ message TrafficCommand
 {
     // The interface version used by the sender (scenario engine).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp of the simulation environment. Zero time is arbitrary
@@ -33,10 +37,18 @@ message TrafficCommand
     // There is no inherent latency for traffic command data, as opposed
     // to sensor data.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The ID of this traffic participant.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier traffic_participant_id = 3;
 
     // Commanded traffic action(s) if any.

osi_trafficcommandupdate.proto

@@ -29,18 +29,30 @@ message TrafficCommandUpdate
 {
     // The interface version used by the sender (traffic participant model).
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional InterfaceVersion version = 1;
 
     // The data timestamp of the simulation environment. Zero time is arbitrary
     // but must be identical for all messages. Zero time does not need to
     // coincide with the UNIX epoch. It is recommended to use zero timestamp as 
     // the starting time point of the simulation.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Timestamp timestamp = 2;
 
     // The ID of this traffic participant which must coincide with a prior sent ID, cf.
     // \c TrafficCommand::traffic_participant_id.
     //
+    // \rules
+    // is_set
+    // \endrules
+    //
     optional Identifier traffic_participant_id = 3;
 
     // Actions which a traffic participant dismisses and which are not yet ended or 

osi_trafficlight.proto

@@ -20,6 +20,7 @@ message TrafficLight
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;

osi_trafficsign.proto

@@ -173,6 +173,7 @@ message TrafficSign
     //
     // \rules
     // is_globally_unique
+    // is_set
     // \endrules
     //
     optional Identifier id = 1;