plexus-python-common 1.0.55__tar.gz → 1.0.56__tar.gz

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python-common
-Version: 1.0.55
+Version: 1.0.56
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -12,6 +12,7 @@ Requires-Dist: boto3-stubs[s3]<1.42,>=1.41
 Requires-Dist: docker>=7.1
 Requires-Dist: fsspec>=2025.10
 Requires-Dist: jinja2>=3.0
+Requires-Dist: jsonschema>=4.0
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown-it-py>=4.0
 Requires-Dist: numpy>=2.3

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/pyproject.toml

@@ -14,6 +14,7 @@ dev = [
     "docker>=7.1",
     "fsspec>=2025.10",
     "jinja2>=3.0",
+    "jsonschema>=4.0",
     "lxml>=6.0",
     "markdown-it-py>=4.0",
     "numpy>=2.3",
@@ -60,6 +61,7 @@ dependencies = [
     "docker>=7.1",
     "fsspec>=2025.10",
     "jinja2>=3.0",
+    "jsonschema>=4.0",
     "lxml>=6.0",
     "markdown-it-py>=4.0",
     "numpy>=2.3",

plexus_python_common-1.0.56/src/plexus/common/resources/tags/unittest.tagset.yaml

@@ -0,0 +1,97 @@
+$namespace: "unittest"
+# language=markdown
+$desc: !markdown |
+  **Unit Test Tagset**
+  
+  A collection of tags designed for annotating and categorizing data in unit tests. This tagset includes categories
+  for camera views, radar views, LiDAR views, environmental conditions, and roadway characteristics. Each tag is
+  defined with a description that provides context for its use in unit testing scenarios, helping to ensure that
+  test cases are accurately annotated and can be easily understood by developers and testers.
+$def:
+  anchored_tags:
+    &anchored_tags
+    anchored:
+      # language=markdown
+      $desc: !markdown |
+        Anchored tags that describe specific perspectives or viewpoints from which data is captured. These tags are
+        typically associated with sensor data and provide critical context for understanding the scene and the
+        information being analyzed. For example, camera views may include front center, front left, front right, side
+        left, side right, rear left, and rear right perspectives, while radar and LiDAR views may include unified,
+        bumper center, bumper left, bumper right, and similar perspectives.
+      $schema:
+        type: object
+        properties:
+          dummy_property:
+            description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under the anchored tags."
+            type: string
+        additionalProperties: true
+    another_anchored:
+      # language=markdown
+      $desc: !markdown |
+        Another set of anchored tags that describe specific perspectives or viewpoints from which data is captured.
+        These tags may be used in different contexts or for different types of sensors, but they serve a similar
+        purpose in providing critical context for understanding the scene and the information being analyzed.
+$tags:
+  level_1_tag:
+    $desc: "This is a level 1 tag that provides a high-level categorization for the data."
+    $schema:
+      type: object
+      properties:
+        dummy_property:
+          description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under this level 1 tag."
+          type: string
+      additionalProperties: true
+    level_2_tag:
+      $desc: "This is a level 2 tag that provides a more specific categorization for the data."
+      level_3_tag: { $desc: "level 3 tag description", <<: *anchored_tags }
+      another_level_3_tag: { $desc: "another level 3 tag description" }
+    another_level_2_tag:
+      $desc: "This is another level 2 tag that provides a different specific categorization for the data."
+      $schema:
+        type: object
+        properties:
+          dummy_property:
+            description: "This is a dummy property that serves as a placeholder for the actual properties that would be defined under this level 2 tag."
+            type: object
+            properties:
+              dummy_sub_property:
+                description: "This is a dummy sub-property that serves as a placeholder for the actual sub-properties that would be defined under this dummy property."
+                type: string
+            additionalProperties: false
+        required: [ dummy_property ]
+        additionalProperties: true
+      <<: *anchored_tags
+  another_level_1_tag:
+    # language=markdown
+    $desc: !markdown |
+      This is another level 1 tag that provides a different high-level categorization for the data. It may be used
+      to group data based on different criteria or characteristics, such as environmental conditions, roadway
+      characteristics, or other relevant factors that are important for unit testing scenarios.
+    $schema:
+      type: object
+      properties:
+        dummy_elements:
+          description: "This is a dummy array property that serves as a placeholder for the actual array properties that would be defined under this level 1 tag."
+          type: array
+          items:
+            type: integer
+            minimum: 0
+          minItems: 1
+          maxItems: 3
+      required: [ dummy_elements ]
+      additionalProperties: true
+    level_2_tag:
+      # language=markdown
+      $desc: !markdown |
+        This is a level 2 tag that provides a more specific categorization for the data under the second level 1 tag.
+        It may be used to further refine the categorization based on specific criteria or characteristics relevant to
+        the second level 1 tag, such as different types of environmental conditions or roadway characteristics.
+      level_3_tag:
+        # language=markdown
+        $desc: !markdown |
+          This is a level 3 tag that provides an even more specific categorization for the data under the level 2 tag
+          of the second level 1 tag. It may be used to further refine the categorization based on very specific
+          criteria or characteristics relevant to the level 2 tag, such as specific weather conditions, road types,
+          or other detailed factors that are important for unit testing scenarios.
+        level_4_tag:
+          $desc: "This is a level 4 tag that provides an even more specific categorization for the data under the level 3 tag. Actually, you can have as many levels as you want, but for the sake of this example, we will stop at level 4."

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/src/plexus/common/resources/tags/universal.tagset.yaml

@@ -1,6 +1,8 @@
 $namespace: "universal"
 # language=markdown
 $desc: !markdown |
+  **Universal Tagset**
+  
   Universal tags applicable across various scenarios, environments, and data types. This tagset provides a common
   vocabulary for describing key attributes of roadway scenes, traffic conditions, environmental factors, and data
   quality issues relevant to autonomous driving and advanced driver-assistance systems (ADAS). The tags are organized
@@ -10,30 +12,282 @@ $desc: !markdown |
 $def:
   camera_views:
     &camera_views
-    unified: { $desc: "unified" }
-    front_center: { $desc: "front center" }
-    front_left: { $desc: "front left" }
-    front_right: { $desc: "front right" }
-    side_left: { $desc: "side left" }
-    side_right: { $desc: "side right" }
-    rear_left: { $desc: "rear left" }
-    rear_right: { $desc: "rear right" }
+    unified:
+      # language=markdown
+      $desc: !markdown |
+        **Unified Camera View**
+        
+        A camera view that combines the fields of view from multiple cameras into a single, cohesive perspective. This
+        view is often used in perception systems to provide a comprehensive understanding of the environment by
+        integrating data from front, side, and rear cameras. The unified camera view can enhance object detection,
+        tracking, and scene understanding by providing a more complete visual representation of the surroundings.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_center:
+      # language=markdown
+      $desc: !markdown |
+        **Front Center Camera View**
+        
+        A camera view that captures the area directly in front of the vehicle, typically aligned with the center of the
+        front bumper. This view is crucial for detecting and tracking objects such as vehicles, pedestrians, and
+        traffic signs in the path of travel. The front center camera provides critical information for lane keeping,
+        adaptive cruise control, and collision avoidance systems.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_left:
+      # language=markdown
+      $desc: !markdown |
+        **Front Left Camera View**
+        
+        A camera view that captures the area to the front left of the vehicle, typically covering the left lane and
+        adjacent areas. This view is important for monitoring traffic in the left lane, detecting pedestrians or
+        cyclists approaching from the left, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_right:
+      # language=markdown
+      $desc: !markdown |
+        **Front Right Camera View**
+        
+        A camera view that captures the area to the front right of the vehicle, typically covering the right lane and
+        adjacent areas. This view is important for monitoring traffic in the right lane, detecting pedestrians or
+        cyclists approaching from the right, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    side_left:
+      # language=markdown
+      $desc: !markdown |
+        **Side Left Camera View**
+        
+        A camera view that captures the area directly to the left of the vehicle, typically covering the left side of
+        the roadway and adjacent areas. This view is important for monitoring traffic in the left lane, detecting
+        pedestrians or cyclists approaching from the left, and providing situational awareness for lane changes and
+        turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    side_right:
+      # language=markdown
+      $desc: !markdown |
+        **Side Right Camera View**
+        
+        A camera view that captures the area directly to the right of the vehicle, typically covering the right side
+        of the roadway and adjacent areas. This view is important for monitoring traffic in the right lane, detecting
+        pedestrians or cyclists approaching from the right, and providing situational awareness for lane changes and
+        turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    rear_left:
+      # language=markdown
+      $desc: !markdown |
+        **Rear Left Camera View**
+        
+        A camera view that captures the area to the rear left of the vehicle, typically covering the left rear lane
+        and adjacent areas. This view is important for monitoring traffic behind the vehicle, detecting pedestrians or
+        cyclists approaching from the rear left, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    rear_right:
+      # language=markdown
+      $desc: !markdown |
+        **Rear Right Camera View**
+        
+        A camera view that captures the area to the rear right of the vehicle, typically covering the right rear lane
+        and adjacent areas. This view is important for monitoring traffic behind the vehicle, detecting pedestrians or
+        cyclists approaching from the rear right, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
   radar_views:
     &radar_views
-    unified: { $desc: "unified" }
-    bumper_center: { $desc: "bumper center" }
-    bumper_left: { $desc: "bumper left" }
-    bumper_right: { $desc: "bumper right" }
+    unified:
+      # language=markdown
+      $desc: !markdown |
+        **Unified Radar View**
+        
+        A radar view that combines the data from multiple radar sensors into a single, cohesive perspective. This view
+        is often used in perception systems to provide a comprehensive understanding of the environment by integrating
+        data from front, side, and rear radars. The unified radar view can enhance object detection, tracking, and
+        scene understanding by providing a more complete representation of the surroundings, especially in adverse
+        weather conditions where cameras may be less effective.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    bumper_center:
+      # language=markdown
+      $desc: !markdown |
+        **Bumper Center Radar View**
+        
+        A radar view that captures the area directly in front of the vehicle, typically aligned with the center of the
+        front bumper. This view is crucial for detecting and tracking objects such as vehicles, pedestrians, and
+        traffic signs in the path of travel. The bumper center radar provides critical information for adaptive cruise
+        control, collision avoidance systems, and low-speed maneuvering.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    bumper_left:
+      # language=markdown
+      $desc: !markdown |
+        **Bumper Left Radar View**
+        
+        A radar view that captures the area to the front left of the vehicle, typically covering the left lane and
+        adjacent areas. This view is important for monitoring traffic in the left lane, detecting pedestrians or
+        cyclists approaching from the left, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    bumper_right:
+      # language=markdown
+      $desc: !markdown |
+        **Bumper Right Radar View**
+        
+        A radar view that captures the area to the front right of the vehicle, typically covering the right lane and
+        adjacent areas. This view is important for monitoring traffic in the right lane, detecting pedestrians or
+        cyclists approaching from the right, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
   lidar_views:
     &lidar_views
-    unified: { $desc: "unified" }
-    front_center: { $desc: "front center" }
-    front_left: { $desc: "front left" }
-    front_right: { $desc: "front right" }
-    side_left: { $desc: "side left" }
-    side_right: { $desc: "side right" }
-    rear_left: { $desc: "rear left" }
-    rear_right: { $desc: "rear right" }
+    unified:
+      # language=markdown
+      $desc: !markdown |
+        **Unified LiDAR View**
+        
+        A LiDAR view that combines the point cloud data from multiple LiDAR sensors into a single, cohesive
+        perspective. This view is often used in perception systems to provide a comprehensive understanding of the
+        environment by integrating data from front, side, and rear LiDAR sensors. The unified LiDAR view can enhance
+        object detection, tracking, and scene understanding by providing a more complete representation of the
+        surroundings, especially in low-light or adverse weather conditions where cameras may be less effective.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_center:
+      # language=markdown
+      $desc: !markdown |
+        **Front Center LiDAR View**
+        
+        A LiDAR view that captures the area directly in front of the vehicle, typically aligned with the center of the
+        front bumper. This view is crucial for detecting and tracking objects such as vehicles, pedestrians, and
+        traffic signs in the path of travel. The front center LiDAR provides critical information for lane keeping,
+        adaptive cruise control, and collision avoidance systems.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_left:
+      # language=markdown
+      $desc: !markdown |
+        **Front Left LiDAR View**
+        
+        A LiDAR view that captures the area to the front left of the vehicle, typically covering the left lane and
+        adjacent areas. This view is important for monitoring traffic in the left lane, detecting pedestrians or
+        cyclists approaching from the left, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    front_right:
+      # language=markdown
+      $desc: !markdown |
+        **Front Right LiDAR View**
+        
+        A LiDAR view that captures the area to the front right of the vehicle, typically covering the right lane and
+        adjacent areas. This view is important for monitoring traffic in the right lane, detecting pedestrians or
+        cyclists approaching from the right, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    side_left:
+      # language=markdown
+      $desc: !markdown |
+        **Side Left LiDAR View**
+        
+        A LiDAR view that captures the area directly to the left of the vehicle, typically covering the left side of
+        the roadway and adjacent areas. This view is important for monitoring traffic in the left lane, detecting
+        pedestrians or cyclists approaching from the left, and providing situational awareness for lane changes and
+        turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    side_right:
+      # language=markdown
+      $desc: !markdown |
+        **Side Right LiDAR View**
+        
+        A LiDAR view that captures the area directly to the right of the vehicle, typically covering the right side of
+        the roadway and adjacent areas. This view is important for monitoring traffic in the right lane, detecting
+        pedestrians or cyclists approaching from the right, and providing situational awareness for lane changes and
+        turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    rear_left:
+      # language=markdown
+      $desc: !markdown |
+        **Rear Left LiDAR View**
+        
+        A LiDAR view that captures the area to the rear left of the vehicle, typically covering the left rear lane
+        and adjacent areas. This view is important for monitoring traffic behind the vehicle, detecting pedestrians or
+        cyclists approaching from the rear left, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
+    rear_right:
+      # language=markdown
+      $desc: !markdown |
+        **Rear Right LiDAR View**
+        
+        A LiDAR view that captures the area to the rear right of the vehicle, typically covering the right rear lane
+        and adjacent areas. This view is important for monitoring traffic behind the vehicle, detecting pedestrians or
+        cyclists approaching from the rear right, and providing situational awareness for lane changes and turns.
+        
+        Examples:
+        
+        - [Case 1](https://image-search.plexus.ai/particular_case_image)
+        - [Case 2](https://image-search.plexus.ai/particular_case_image)
 $tags:
   environment:
     # language=markdown
@@ -479,27 +733,111 @@ $tags:
       # language=markdown
       $desc: !markdown |
         Roadway layout types that describe the overall configuration of the road and its lanes. These tags capture
-        specific layout types such as single way, undivided two way, divided two way, and unknown. Each layout type has
+        specific layout types such as single way, undivided two-way, divided two-way, and unknown. Each layout type has
         unique implications for traffic flow, driver behavior, and sensor coverage, making them important for scenario
         analysis and data annotation. For example, a single way layout typically involves one lane of traffic in each
-        direction with no physical separation, while a divided two way layout includes a physical barrier or median
+        direction with no physical separation, while a divided two-way layout includes a physical barrier or median
         separating opposing traffic flows.
-      single_way: { $desc: "single way" }
-      undivided_two_way: { $desc: "undivided two way" }
-      divided_two_way: { $desc: "divided two way" }
+      single_way:
+        # language=markdown
+        $desc: !markdown |
+          **Single Way Layout**
+          
+          A roadway configuration where traffic flows in both directions without any physical separation, such as a
+          centerline or median. This layout typically involves one lane of traffic in each direction, and drivers must
+          exercise caution when passing or making turns due to the potential for head-on collisions. Sensor coverage
+          may be more challenging in single way layouts due to the lack of clear lane boundaries and the presence of
+          oncoming traffic.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      undivided_two_way:
+        # language=markdown
+        $desc: !markdown |
+          **Undivided Two Way Layout**
+          
+          A roadway configuration where traffic flows in both directions with a painted centerline but no physical
+          separation, such as a median or barrier. This layout typically involves one lane of traffic in each direction,
+          and drivers must exercise caution when passing or making turns due to the potential for head-on collisions.
+          Sensor coverage may be more challenging in undivided two-way layouts due to the presence of oncoming traffic
+          and the potential for lane departures.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      divided_two_way:
+        # language=markdown
+        $desc: !markdown |
+          **Divided Two Way Layout**
+          
+          A roadway configuration where traffic flows in both directions with a physical separation, such as a median or
+          barrier. This layout typically involves one or more lanes of traffic in each direction, and the physical
+          separation helps to reduce the risk of head-on collisions. Sensor coverage may be improved in divided two-way
+          layouts due to the presence of clear lane boundaries and reduced interaction with oncoming traffic.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
       unknown: { $desc: "unknown" }
     lane_config:
       # language=markdown
       $desc: !markdown |
         Lane configuration types that describe the number and arrangement of lanes on the roadway. These tags capture
-        specific lane configurations such as single lane, two lane, multi lane, and unknown. Each configuration has
+        specific lane configurations such as single lane, two lane, multi-lane, and unknown. Each configuration has
         unique implications for traffic flow, driver behavior, and sensor coverage, making them important for scenario
         analysis and data annotation. For example, a single lane configuration typically involves one lane of traffic in
-        each direction with no passing allowed, while a multi lane configuration includes multiple lanes in each
+        each direction with no passing allowed, while a multi-lane configuration includes multiple lanes in each
         direction with opportunities for passing and lane changes.
-      single_lane: { $desc: "single lane" }
-      two_lane: { $desc: "two lane" }
-      multi_lane: { $desc: "multi lane" }
+      single_lane:
+        # language=markdown
+        $desc: !markdown |
+          **Single Lane Configuration**
+          
+          A roadway configuration where there is only one lane of traffic in each direction, with no opportunities for
+          passing or lane changes. This configuration typically involves a centerline to separate opposing traffic
+          flows,
+          and drivers must exercise caution when making turns or navigating around obstacles due to the potential for
+          head-on collisions. Sensor coverage may be more challenging in single lane configurations due to the presence
+          of oncoming traffic and the potential for lane departures.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      two_lane:
+        # language=markdown
+        $desc: !markdown |
+          **Two Lane Configuration**
+          
+          A roadway configuration where there are two lanes of traffic in each direction, allowing for passing and lane
+          changes. This configuration typically involves a centerline to separate opposing traffic flows, and drivers
+          must exercise caution when making turns or navigating around obstacles due to the potential for head-on
+          collisions. Sensor coverage may be improved in two lane configurations due to the presence of clear lane
+          boundaries and reduced interaction with oncoming traffic.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      multi_lane:
+        # language=markdown
+        $desc: !markdown |
+          **Multi Lane Configuration**
+          
+          A roadway configuration where there are multiple lanes of traffic in each direction, allowing for passing,
+          lane changes, and higher traffic volumes. This configuration typically involves a centerline to separate
+          opposing traffic flows, and drivers must exercise caution when making turns or navigating around obstacles due
+          to the potential for head-on collisions. Sensor coverage may be improved in multi-lane configurations due to
+          the presence of clear lane boundaries and reduced interaction with oncoming traffic.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
       unknown: { $desc: "unknown" }
     shoulder:
       # language=markdown
@@ -531,11 +869,11 @@ $tags:
           **Median Shoulder**
           
           A shoulder area located in the median between opposing traffic flows, often separated by a physical barrier or
-          marked with a painted buffer. Median shoulders can provide a refuge area for disabled vehicles and may
-          enhance safety by separating opposing traffic, but they may also have limited width and accessibility. Drivers
-          may use median shoulders for emergency stops or to avoid obstacles, but they should exercise caution due to
-          potential traffic from both directions. Sensor coverage in median shoulders may be limited, making them an
-          important consideration for scenario analysis and data annotation.
+          marked with a painted buffer. Median shoulders can provide a refuge area for disabled vehicles and may enhance
+          safety by separating opposing traffic, but they may also have limited width and accessibility. Drivers may use
+          median shoulders for emergency stops or to avoid obstacles, but they should exercise caution due to potential
+          traffic from both directions. Sensor coverage in median shoulders may be limited, making them an important
+          consideration for scenario analysis and data annotation.
           
           Examples:
           
@@ -747,9 +1085,52 @@ $tags:
         for driving behavior, vehicle dynamics, and sensor performance, making them important for scenario analysis and
         data annotation. For example, tunnels can create confined spaces with limited visibility and unique lighting
         conditions, while bridges/overpasses may involve elevation changes and exposure to wind.
-      tunnel: { $desc: "tunnel" }
-      bridge: { $desc: "bridge/overpass" }
-      underpass: { $desc: "underpass" }
+      tunnel:
+        # language=markdown
+        $desc: !markdown |
+          **Tunnel**
+          
+          A roadway feature that involves a passage through or under a structure, such as a mountain, hill, or urban
+          area. Tunnels can create confined spaces with limited visibility and unique lighting conditions, which can
+          affect driver behavior and sensor performance. Drivers may need to adjust their speed and following distance
+          when entering or exiting tunnels due to changes in visibility and road conditions. Sensor coverage in tunnels
+          may be limited, making them an important consideration for scenario analysis and data annotation.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      bridge:
+        # language=markdown
+        $desc: !markdown |
+          **Bridge/Overpass**
+          
+          A roadway feature that involves a structure spanning a physical obstacle, such as a river, valley, or another
+          road. Bridges and overpasses may involve elevation changes and exposure to wind, which can affect driver
+          behavior and vehicle dynamics. Drivers may need to adjust their speed and following distance when crossing
+          bridges or overpasses due to changes in road conditions and potential crosswinds. Sensor coverage on bridges
+          and overpasses may be affected by the structure itself, making them an important consideration for scenario
+          analysis and data annotation.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      underpass:
+        # language=markdown
+        $desc: !markdown |
+          **Underpass**
+          
+          A roadway feature that involves a passage under a structure, such as a bridge, railway, or urban area.
+          Underpasses can create confined spaces with limited visibility and unique lighting conditions, which can
+          affect driver behavior and sensor performance. Drivers may need to adjust their speed and following distance
+          when entering or exiting underpasses due to changes in visibility and road conditions. Sensor coverage in
+          underpasses may be limited, making them an important consideration for scenario analysis and data annotation.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
       unknown: { $desc: "unknown" }
     geometry:
       # language=markdown
@@ -760,11 +1141,108 @@ $tags:
         them important for scenario analysis and data annotation. For example, a straight segment typically allows for
         higher speeds and better visibility, while a curved segment may require more cautious driving and can create
         blind spots.
-      curved: { $desc: "curved segment" }
-      incline: { $desc: "incline segment" }
-      decline: { $desc: "decline segment" }
-      hill_crest: { $desc: "hill crest" }
-      sag: { $desc: "sag segment" }
+      curved:
+        # language=markdown
+        $desc: !markdown |
+          **Curved Segment**
+          
+          A roadway segment that features a horizontal curvature, requiring drivers to navigate a bend in the road.
+          Curved segments can vary in radius and degree of curvature, affecting vehicle dynamics and driver behavior.
+          Drivers may need to reduce speed and adjust their steering when navigating curved segments, especially if the
+          curve is sharp or if visibility is limited. Sensor performance may also be affected by curved segments due to
+          changes in the field of view and potential occlusions.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+        $schema:
+          type: object
+          properties:
+            curvature_radius:
+              type: number
+              description: "The radius of the curve in meters"
+              minimum: 0
+          required: [ curvature_radius ]
+          additionalProperties: true
+      incline:
+        # language=markdown
+        $desc: !markdown |
+          **Incline Segment**
+          
+          A roadway segment that features a positive vertical grade, requiring drivers to navigate an uphill slope.
+          Incline segments can vary in steepness and length, affecting vehicle dynamics and driver behavior. Drivers may
+          need to reduce speed and adjust their acceleration when navigating incline segments, especially if the incline
+          is steep or if the vehicle is heavily loaded. Sensor performance may also be affected by incline segments due
+          to changes in the field of view and potential occlusions.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+        $schema:
+          type: object
+          properties:
+            grade_percentage:
+              type: number
+              description: "The grade of the incline in percentage"
+              minimum: 0
+          required: [ grade_percentage ]
+          additionalProperties: false
+      decline:
+        # language=markdown
+        $desc: !markdown |
+          **Decline Segment**
+          
+          A roadway segment that features a negative vertical grade, requiring drivers to navigate a downhill slope.
+          Decline segments can vary in steepness and length, affecting vehicle dynamics and driver behavior. Drivers may
+          need to reduce speed and adjust their braking when navigating decline segments, especially if the decline is
+          steep or if the vehicle is heavily loaded. Sensor performance may also be affected by decline segments due to
+          changes in the field of view and potential occlusions.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+        $schema:
+          type: object
+          properties:
+            grade_percentage:
+              type: number
+              description: "The grade of the decline in percentage"
+              maximum: 0
+          required: [ grade_percentage ]
+          additionalProperties: false
+      hill_crest:
+        # language=markdown
+        $desc: !markdown |
+          **Hill Crest Segment**
+          
+          A roadway segment that features a vertical crest, where the road reaches a high point before descending. Hill
+          crest segments can create blind spots and limited visibility for drivers, affecting driver behavior and sensor
+          performance. Drivers may need to reduce speed and exercise caution when navigating hill crest segments,
+          especially if the crest is sharp or if there are potential obstacles on the other side. Sensor coverage may
+          also be affected by hill crest segments due to changes in the field of view and potential occlusions.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
+      sag:
+        # language=markdown
+        $desc: !markdown |
+          **Sag Segment**
+          
+          A roadway segment that features a vertical sag, where the road dips down before ascending. Sag segments can
+          create blind spots and limited visibility for drivers, affecting driver behavior and sensor performance.
+          Drivers may need to reduce speed and exercise caution when navigating sag segments, especially if the sag is
+          sharp or if there are potential obstacles in the dip. Sensor coverage may also be affected by sag segments due
+          to changes in the field of view and potential occlusions.
+          
+          Examples:
+          
+          - [Case 1](https://image-search.plexus.ai/particular_case_image)
+          - [Case 2](https://image-search.plexus.ai/particular_case_image)
   traffic:
     # language=markdown
     $desc: !markdown |

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/src/plexus/common/utils/tagutils.py

@@ -10,6 +10,7 @@ from collections.abc import Generator, Mapping, Sequence
 from typing import Self
 
 import jinja2
+import jsonschema
 import pydantic as pdt
 import sqlalchemy as sa
 import sqlalchemy.dialects.sqlite as sa_sqlite
@@ -60,6 +61,7 @@ class RichDesc(object):
 class Tag(object):
     name: str
     desc: str | RichDesc | None
+    schema: JsonObject | None = None
 
     @property
     def tag_parts(self) -> list[str]:
@@ -69,6 +71,17 @@ class Tag(object):
     def parent_tag_name(self) -> str | None:
         return head_or_none(self.name.rsplit(":", 1))
 
+    def validate(self, props: JsonType | None, *, raise_on_error: bool = False) -> bool:
+        if self.schema is None or props is None:
+            return True
+        try:
+            jsonschema.Draft7Validator(self.schema).validate(props)
+            return True
+        except (jsonschema.ValidationError, jsonschema.SchemaError):
+            if raise_on_error:
+                raise
+            return False
+
 
 class Tagset(Sequence[Tag], Mapping[str, Tag]):
     def __init__(self, namespace: str, desc: str | RichDesc) -> None:
@@ -132,6 +145,10 @@ class Tagset(Sequence[Tag], Mapping[str, Tag]):
 
         return list(dicttree_lineage(self.tags_tree, child.tag_parts[:-1]))
 
+    def validate(self, tag_name: str, props: JsonType | None, *, raise_on_error: bool = False) -> bool:
+        tag = self.get(tag_name)
+        return False if tag is None else tag.validate(props, raise_on_error=raise_on_error)
+
 
 class MutableTagset(Tagset):
 
@@ -201,10 +218,17 @@ def populate_tagset(tagset_spec: JsonObject) -> Tagset:
             if isinstance(desc, dict):
                 desc = RichDesc(**desc)
 
-            yield Tag(name=name, desc=desc)
+            schema = tag_def.get("$schema")
+            if schema is not None:
+                try:
+                    jsonschema.Draft7Validator.check_schema(schema)
+                except jsonschema.SchemaError as e:
+                    raise ValueError(f"invalid JSON schema for tag '{name}'") from e
+
+            yield Tag(name=name, desc=desc, schema=schema)
 
         for child_name, child_tag_def in tag_def.items():
-            if child_name == "$desc":
+            if child_name in ("$desc", "$schema"):
                 continue
 
             if not isinstance(child_name, str):

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/src/plexus_python_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python-common
-Version: 1.0.55
+Version: 1.0.56
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -12,6 +12,7 @@ Requires-Dist: boto3-stubs[s3]<1.42,>=1.41
 Requires-Dist: docker>=7.1
 Requires-Dist: fsspec>=2025.10
 Requires-Dist: jinja2>=3.0
+Requires-Dist: jsonschema>=4.0
 Requires-Dist: lxml>=6.0
 Requires-Dist: markdown-it-py>=4.0
 Requires-Dist: numpy>=2.3

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/src/plexus_python_common.egg-info/SOURCES.txt

@@ -48,6 +48,7 @@ src/plexus/common/carto/OSMWay.py
 src/plexus/common/carto/__init__.py
 src/plexus/common/resources/__init__.py
 src/plexus/common/resources/tags/__init__.py
+src/plexus/common/resources/tags/unittest.tagset.yaml
 src/plexus/common/resources/tags/universal.tagset.yaml
 src/plexus/common/utils/__init__.py
 src/plexus/common/utils/apiutils.py

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/src/plexus_python_common.egg-info/requires.txt

@@ -4,6 +4,7 @@ boto3-stubs[s3]<1.42,>=1.41
 docker>=7.1
 fsspec>=2025.10
 jinja2>=3.0
+jsonschema>=4.0
 lxml>=6.0
 markdown-it-py>=4.0
 numpy>=2.3

{plexus_python_common-1.0.55 → plexus_python_common-1.0.56}/test/plexus_tests/common/utils/tagutils_test.py

@@ -6,6 +6,7 @@ import unittest
 
 import ddt
 from iker.common.utils.dtutils import dt_parse_iso
+from iker.common.utils.jsonutils import JsonObject
 
 from plexus.common.utils.tagutils import MutableTagset, Tag, TagCache, Tagset
 from plexus.common.utils.tagutils import predefined_tagsets, render_tagset_markdown_readme
@@ -32,6 +33,54 @@ class TagUtilsTest(unittest.TestCase):
 
             print(markdown)
 
+    data_tag_validate = [
+        ("level_1_tag", {"dummy_property": "dummy_value"}, True,),
+
+        # extra keys should not cause validation failure, as specified in the schema with
+        # "additionalProperties": True
+        ("level_1_tag", {"dummy_property": "dummy_value", "extra_key": True}, True,),
+
+        # missing keys should not cause validation failure, as specified in the schema with "required": []
+        ("level_1_tag", {"extra_key": True}, True,),
+
+        # schema absence should not cause validation failure
+        ("level_1_tag:level_2_tag", {"dummy_property": "dummy_value"}, True,),
+
+        ("level_1_tag:another_level_2_tag", {"dummy_property": {"dummy_sub_property": "dummy_value"}}, True,),
+
+        # extra keys in nested properties should cause validation failure, as specified in the schema with
+        # "additionalProperties": False
+        ("level_1_tag:another_level_2_tag",
+         {"dummy_property": {"dummy_sub_property": "dummy_value", "extra_key": True}},
+         False,),
+
+        # bad type in nested properties should cause validation failure
+        ("level_1_tag:another_level_2_tag",
+         {"dummy_property": {"dummy_sub_property": 0}},
+         False,),
+
+        # at least one element should be present in the array, as specified in the schema with "minItems": 1
+        ("another_level_1_tag", {"dummy_elements": []}, False,),
+
+        # at most 3 elements should be present in the array, as specified in the schema with "maxItems": 3
+        ("another_level_1_tag", {"dummy_elements": [1, 2, 3, 4, 5]}, False,),
+
+        # integers in the array should be non-negative, as specified in the schema with "minimum": 0
+        ("another_level_1_tag", {"dummy_elements": [-1]}, False,),
+    ]
+
+    @ddt.idata(data_tag_validate)
+    @ddt.unpack
+    def test_tag_validate(self, tag: str, props: JsonObject, should_pass: bool):
+        tagset = predefined_tagsets().get("unittest")
+
+        if should_pass:
+            self.assertTrue(tagset.validate(tag, props))
+        else:
+            self.assertFalse(tagset.validate(tag, props))
+            with self.assertRaises(Exception):
+                tagset.validate(tag, props, raise_on_error=True)
+
     def test_tag_cache(self):
         tagset = MutableTagset(namespace="tagset", desc="A dummy tagset for testing")
         tagset.add(Tag(name="dummy:foo", desc="A dummy tag for testing"))