Scoping rules

Scoped and rule-based properties

In the real world, many facts and rules affecting entities have only a partial application, meaning they don't apply everywhere, or they don't apply at all times, or to everyone, or to all sets of external conditions. For example, access restrictions on a road segment might not apply to all people or all kinds of vehicles, or they might vary according to the day of the week.

The Overture schema uses two related concepts to capture the partial application of facts and rules: scoped values and rule-based properties.

Scoped values and scoping properties

A scoped value is a value which only applies within a limited scope. Most scoped values are rules in the rule lists of rule-based properties. However, scoped values also exist outside of rule-based properties. For example, a signpost property belonging to a road segment might be geometrically scoped to its position along the road.

The scope in which a scoped value applies is controlled by one or more special child properties of the value known as scoping properties.

Geometric scoping (linear referencing)

Description

The geometric scoping properties at and between limit the scope of their parent value to a position or range of positions, respectively, along a segment's geometry. When the parent value is a rule object, the rule only matches the position or range of positions specified in the at or between property.

The value of the at property is a single real number a where 0 ≤ a ≤ 1. It represents a discrete position along the segment's geometry. The value of the between property is a pair of numbers [a, b] where 0 ≤ a < b ≤ 1. It represents a range of positions along the segment's geometry. The numbers a and b are interpreted as percentage displacements along the parent segment's geometry starting from the start of the segment. (The terms "start" and "end" are explained in Shape and connectivity.)

So, for example, the scoping property "at": 0.15 scopes its parent value to the position on the segment that is displaced 15% of the segment length from the start.

The position along the segment geometry described by "at": 0.15.

The scoping property "between": [0.35, 0.75] scopes its parent value to the range of positions on the segment beginning at 35% and extending to 75% of the segment length from the start.

The range on the segment geometry described by "between": [0.35, 0.75].

Example

The example below shows a road segment whose speed limit is defined by two geometrically-scoped speed limit rules:

---
id: overture:transportation:example:geometric-scoping
type: Feature
geometry:
  type: LineString
  coordinates: [[0, 0], [1, 1]]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: primary
  speed_limits:
    - between: [0, 0.15]
      max_speed:
        value: 100
        unit: km/h
    - between: [0.15, 1]
      max_speed:
        value: 60
        unit: km/h

Temporal scoping (opening hours)

Description

The temporal, or time-based, scoping construct when: { during: "..." } limits the scope of its parent value to one or more recurring time ranges. When the parent value is a rule object, the rule only matches the time range or time ranges specified in the during property.

The during property must contain a string expressed in the OpenStreetMap opening hours specification.

Example

The example below shows a road segment with a temporally-scoped access restriction rule. The rule states that non-bus travellers are prohibited from access to the segment on weekdays between 3PM and 6PM.

---
id: overture:transportation:example:temporal-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-122.90019762265949, 49.20784664905824]
    - [-122.9003738558948, 49.207833436710956]
    - [-122.90052986564378, 49.207871186265805]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: unknown
  access_restrictions:
    - access_type: denied
      when:
        mode: [bus]
        during: "Mo-Fr 15:00-18:00"

Subjective scoping

Subjective scoping means that the scope of a property can be constrained based on subjective factors like who or what is travelling on the transportation network, or how they are doing it.

The Overture transportation schema supports the following subjective factors:

1. Travel mode
2. Heading
3. Purpose of use
4. Status or membership in a recognized group
5. Vehicle attributes

The sub-headings below explain each of these subjective factors in greater detail.

Travel-mode scoping

A travel mode is a way of moving about the transportation network, for example driving in a motor vehicle, or, more specifically, driving in a high-occupancy vehicle.

The property construct when: { mode: [...] } limits the scope its parent value to apply only to people or things travelling using the listed travel modes.

To dive deeper into this topic, see the page on travel modes.

Heading

Description

Heading scoping limits the the scope of a parent value to apply only when the traveller is proceeding along the segment geometry in the named direction, either forward or backward. (The directions forward and backward are defined on the shape and connectivity page.)

The property construct when: { heading: forward|backward } applies heading scoping to a parent value.

Example

The example below shows a road segment with multiple heading-scoped access restriction rules. The rules allow all standard travel modes for the segment class to travel in the forward direction, but only allow buses to travel in the backward direction.

---
id: overture:transportation:example:subjective-heading-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-1.3023158, 54.5579329]
    - [-1.3020090, 54.5577898]
    - [-1.3014511, 54.5575155]
    - [-1.3009618, 54.5572737]
    - [-1.3004518, 54.5570288]
    - [-1.3003009, 54.5569580]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: primary
  access_restrictions:
    - access_type: denied
      when: { heading: backward }
    - access_type: allowed
      when:
        heading: backward
        mode: [bus]

Purpose of use scoping

Description

Usage purpose scoping limits the scope of a parent value to apply only when the user is using the feature for one of the listed purposes. This type of scoping is common when it matters that a person is in the process of doing something like making a delivery or acting as the customer of a business.

The property construct when: { using: [...] } applies usage purpose scoping to a parent value.

Example

The example below shows a road segment representing a hotel driveway where through traffic is not permitted (only usage by hotel customers or as a final destination is allowed):

---
id: overture:transportation:example:subjective-usage-purpose-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12700676422021, 49.279826628301635]
    - [-123.12680748254229, 49.27995121574301]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: tertiary
  access_restrictions:
    - access_type: denied
    - access_type: allowed
      when: { using: [as_customer, at_destination] }

Status scoping (membership in a recognized group)

Description

Status scoping limits the scope of a parent value to apply only when the user has a certain recognized status or is a member of a recognized group. This type of scoping is useful when it matters whether a person or thing has a recognized characteristic, such as holding a permit or being an employee of a business or student at an academic institution.

The property construct when: { recognized: [...] } applies status scoping to a parent value.

Example

The example below shows a road segment modeling a private condominium tower driveway where access is denied to the general public, but allowed to privately-authorized individuals, such as condo unit owners:

---
id: overture:transportation:example:subjective-status-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12791513926058, 49.287502049554945]
    - [-123.12795068403449, 49.287522915661725]
    - [-123.12797769806272, 49.28756882106529]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: tertiary
  access_restrictions:
    - access_type: denied
    - access_type: allowed
      when: { recognized: [as_private] }

Vehicle attributes scoping

Description

Vehicle attribute scoping limits the scope of a parent value to apply only when the vehicle in use meets certain criteria.

The property construct when: { vehicle: [{ dimension: ..., comparison: ..., value: ... }] } applies vehicle attributes scoping to a parent value.

Note that vehicle attribute scoping can overlap to some degree with travel mode scoping. For example, some access rules may be scoped to the travel mode "heavy goods vehicle", while another equivalent access rule could be scoped to the vehicle attribute "gross vehicle weight".

Example

---
id: overture:transportation:example:subjective-vehicle-attributes-scoping
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.12791513926058, 49.287502049554945]
    - [-123.12795068403449, 49.287522915661725]
    - [-123.12797769806272, 49.28756882106529]
properties:
  theme: transportation
  type: segment
  version: 1
  subtype: road
  class: residential
  access_restrictions:
    - access_type: denied
      when:
        vehicle:
          - dimension: weight
            comparison: greater_than
            value: 23
            unit: 't'

Rules and rule-based properties

A rule-based property is a property whose value in a given situation is determined by evaluating a list of rules against the facts applicable to that situation. Each individual rule in the list of rules is itself a scoped value, a scoped value, and the assessment of which rule applies to a given set of facts is done by the rule evaluation algorithm.

Absolute form

There are cases when specifying a property value using rules makes sense, and cases where doing so is unnecessarily complicated because the real-world entity being modeled has a single unchanging state which is the same in all fact situations. In these cases, most rule-based properties support a simpler absolute form without a list of rules.

Rule evaluation algorithm

Given a rule-based property, the actual value of the property in a given fact pattern is determined by a three-step process: first, all matching rules are identified; second, the single determining rule is chosen if possible; lastly, if there is no applicable rule, an appropriate default value may be assumed.

1. Matching rules. For a given rule and a given set of facts, the rule matches the facts if the scope of the rule contains all the facts, i.e. the facts fit within all of the scoping properties expressed in the rule. The matching criteria for a rule can be thought of as the logical AND of all the scoping properties expressed in the rule.
2. Determining rule. For a given rule-based property and a given set of facts, at most one rule can determine the property value. If only one rule matches, that rules determines the property value. If more than one rule matches, the last matching rule in the list determines the value. (This is similar to how OpenStreetMap conditional restrictions evaluated.) Therefore it is important to write more general rules before more specific ones in a rule list.
3. Fallback to default. If there are no matching rules, an appropriate default value may apply, depending on the property being evaluated.