Transportation Destinations (#176)

* destinations schema

* revert accidental change to unrelated counterexample

* add eols

* refactor destination schema proposal to model the data on the 'from' segment instead of the 'to'.

* symbols independent of labels; updates to examples and counterexamples

* update descriptions

* revert road; minor touchoups

* either labels or symbols myst be present

* either labels or symbols must be present, but both is also valid, replace the required oneOf with anyOf

* fix place->unknown; remove deprecated update_time from example

* remove deprecated update_time from the new counterexamples

* revert accidental added property

* cleanup

counterexamples/transportation/segment/road/bad-road-destinations.yaml

@@ -0,0 +1,48 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value: Seattle
+        type: unknown
+      - value: Seattle
+        type: unknown
+      - value: Redmond
+      - value: 
+        foo: bar
+        type: unknown
+      - value: Bellevue
+        type: other
+      - value: Main Street
+        type: street
+      - value: I90
+        type: route
+      symbols:
+      - airport
+      from:
+      - segment_id: overture:transportation:segment:234
+      - segment_id: overture:transportation:segment:567
+        connector_id: overture:transportation:connector:567
+        foo: bar
+        when:
+          heading: forward
+      to_connector_id: overture:transportation:connector:123
+      final_heading: backward
+    - labels:
+      - value: Kirkland
+        type: unknown
+      from:
+      - segment_id: overture:transportation:segment:567
+        connector_id: overture:transportation:connector:567
+  ext_expected_errors:
+    - "[I#/properties/destinations/0/label] items at index 0 and 1 are equal"

counterexamples/transportation/segment/road/destinations/bad-road-destinations-bad-label-type.yaml

@@ -0,0 +1,27 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value: Seattle
+        type: bad_type
+      symbols:
+      - airport
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+  ext_expected_errors:
+    - "[I#/properties/destinations/0/labels/0/type] [S#/$defs/propertyDefinitions/destinationLabelType/enum] value must be one of"

counterexamples/transportation/segment/road/destinations/bad-road-destinations-duplicate.yaml

@@ -0,0 +1,29 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value: Seattle
+        type: unknown
+      - value: Seattle
+        type: unknown
+      symbols:
+      - airport
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+  ext_expected_errors:
+    - "[I#/properties/destinations/0/labels] items at index 0 and 1 are equal"

counterexamples/transportation/segment/road/destinations/bad-road-destinations-empty-label-value.yaml

@@ -0,0 +1,27 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value:
+        type: unknown
+      symbols:
+      - airport
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+  ext_expected_errors:
+    - "[I#/properties/destinations/0/labels/0/value] [S#/$defs/propertyDefinitions/destinations/items/properties/labels/items/properties/value/type] expected string, but got null"

counterexamples/transportation/segment/road/destinations/bad-road-destinations-invalid-symbol.yaml

@@ -0,0 +1,27 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value: Seattle
+        type: unknown
+      symbols:
+      - bad_symbol
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+  ext_expected_errors:
+    - "[I#/properties/destinations/0] [S#/$defs/propertyDefinitions/destinationSignSymbol/enum] value must be one of ..."

counterexamples/transportation/segment/road/destinations/bad-road-destinations-missing-final_heading.yaml

@@ -0,0 +1,26 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - labels:
+      - value: Seattle
+        type: unknown
+      symbols:
+      - airport
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+  ext_expected_errors:
+    - "[I#/properties/destinations/0] [S#/$defs/propertyDefinitions/destinations/items/required] missing properties: 'final_heading'"

examples/transportation/segment/road/destinations/road-destinations.yaml

@@ -0,0 +1,41 @@
+---
+id: overture:transportation:segment:example:destinations:1
+type: Feature
+geometry:
+  type: LineString
+  coordinates: [[0, 0], [1, 1]]
+properties:
+  theme: transportation
+  type: segment
+  subtype: road
+  class: secondary
+  version: 0
+  connector_ids: [overture:transportation:connector:123, overture:transportation:connector:678]
+  destinations:
+    - when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+      labels:
+      - value: Seattle
+        type: unknown
+      - value: Main Street
+        type: street
+      - value: I90
+        type: route_ref
+      symbols:
+      - motorway
+      - airport  
+    - when:
+        heading: backward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward
+      labels:
+      - value: Redmond
+        type: unknown
+      - value: I5
+        type: toward_route_ref

examples/transportation/segment/road/road.yaml

@@ -57,3 +57,17 @@ properties:
           connector_id: overture:transportation:connector:456
       final_heading: backward
       when: {heading: backward}
+  destinations:
+    - labels:
+      - value: Seattle
+        type: unknown
+      - value: I 90
+        type: route_ref
+      symbols:
+      - airport
+      when:
+        heading: forward
+      from_connector_id: overture:transportation:connector:123
+      to_connector_id: overture:transportation:connector:123
+      to_segment_id: overture:transportation:segment:567
+      final_heading: backward

schema/transportation/segment.yaml

@@ -30,6 +30,7 @@ properties:
         then:
           required: [class]
           properties:
+            destinations: { "$ref": "#/$defs/propertyDefinitions/destinations" }
             lanes: { "$ref": "#/$defs/propertyContainers/lanesContainer" }
             prohibited_transitions: { "$ref": "#/$defs/propertyContainers/prohibitedTransitionsContainer" }
             road_surface: { "$ref": "#/$defs/propertyContainers/surfaceContainer"}
@@ -62,6 +63,81 @@ properties:
       routes: { "$ref": "#/$defs/propertyDefinitions/routes" }
 "$defs":
   propertyDefinitions:
+    destinationLabelType:
+      description: >-
+        The type of object of the destination label.
+      type: string
+      enum: 
+      - street
+      - country 
+      - route_ref
+      - toward_route_ref
+      - unknown
+    destinations:
+      description: >-
+        Describes objects that can be reached by following a transportation segment in the
+        same way those objects are described on signposts or ground writing that a traveller
+        following the segment would observe in the real world. This allows navigation systems
+        to refer to signs and observable writing that a traveller actually sees.
+      type: array
+      items:
+        type: object
+        unevaluatedProperties: false
+        required: [from_connector_id, to_connector_id, to_segment_id, final_heading]
+        anyOf:
+          - required: [labels]
+          - required: [symbols]
+        properties:
+          labels:
+            description: >-
+              Labeled destinations that can be reached by following the segment.
+            type: array
+            items:
+              type: object
+              unevaluatedProperties: false
+              required: [value, type]
+              properties:
+                value:
+                  description: >-
+                    Names the object that is reached
+                  type: string
+                  pattern: ^(\S.*)?\S$
+                type: { "$ref": "#/$defs/propertyDefinitions/destinationLabelType" }
+            minItems: 1
+            uniqueItems: true
+          symbols:
+            description: >-
+              A collection of symbols or icons present on the sign next to current 
+              destination label.
+            type: array
+            items: { "$ref": "#/$defs/propertyDefinitions/destinationSignSymbol" }
+            uniqueItems: true
+            minLength: 1            
+          from_connector_id:          
+            description: >-
+              Identifies the point of physical connection on this segment before which
+              the destination sign or marking is visible.
+            type: string
+          to_segment_id:
+            description: >-
+              Identifies the segment to transition to reach the destination(s) labeled 
+              on the sign or marking.
+            type: string
+          to_connector_id:
+            description: >-
+              Identifies the point of physical connection on the segment identified by 
+              'to_segment_id' to transition to for reaching the destination(s).
+            type: string
+          when:
+            allOf:
+              - "$ref": "#/$defs/propertyContainers/headingScopeContainer"
+            minProperties: 1
+            unevaluatedProperties: false
+          final_heading:
+            description: >-
+              Direction of travel on the segment identified by 'to_segment_id' that leads 
+              to the destination.
+            "$ref": "#/$defs/propertyDefinitions/heading"    
     roadClass:
       description:
         Captures the kind of road and its position in the road network
@@ -137,6 +213,31 @@ properties:
       enum: [ vehicle, motor_vehicle, car, truck, motorcycle, foot, bicycle, bus, hgv, hov, emergency ]
       "$comment": >-
         motor_vehicle includes car, truck and motorcycle
+    destinationSignSymbol:
+      description: >-
+        Indicates what special symbol/icon is present on a signpost, visible as road marking or similar.
+      type: string
+      enum: 
+      - motorway
+      - airport
+      - hospital
+      - center             # center of a locality, city center or downtown, from centre in raw OSM value
+      - industrial
+      - parking
+      - bus
+      - train_station
+      - rest_area
+      - ferry
+      - motorroad
+      - fuel
+      - viewpoint
+      - fuel_diesel
+      - food               # 'food', 'restaurant' in OSM
+      - lodging
+      - info
+      - camp_site
+      - interchange
+      - restrooms          # 'toilets' in OSM
     roadFlag:
       description: Simple flags that can be on or off for a road segment
       type: string