Skip to main content

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)​

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.

Diagram showing a single geometrically-scoped positionDiagram showing a single geometrically-scoped position

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.

Diagram showing a geometrically-scoped rangeDiagram showing a geometrically-scoped range

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

Temporal scoping (opening hours)​

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.

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​

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.

Purpose of use scoping​

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.

Status scoping (membership in a recognized group)​

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.

Vehicle attributes scoping​

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".

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.

Consider the following two examples of road segments. On the left is a section from a simple two-lane bidirectional city street in which there is always one lane of traffic flowing in each direction. On the right is a section from a one-way city street in which two of the lanes are only available for driving at certain times of the day, being reserved for parking at other times. In the example on the left, the lane list is specified absolutely; while in the example on the right, it is given as a list of temporally-scoped lane rules.

---
id: overture:transportation:example:lanes-absolute
type: Feature
geometry:
  type: LineString
  coordinates:
    - [-123.13174398677468, 49.28492173297815]
    - [-123.13015725772073, 49.283923094445726]
properties:
  theme: transportation
  type: segment
  version: 2
  subtype: road
  class: secondary
  lanes:
    - value:
      - direction: backward
      - direction: forward

An absolute list of lanes.

---
id: overture:transportation:example:lanes-rule
type: Feature
geometry:
  type: LineString
  coordinates:
    - - -123.12244656918179
      - 49.280940587393815
    - - -123.12562968007902
      - 49.27884862879665
properties:
  theme: transportation
  type: segment
  version: 0
  update_time: "2023-06-16T15:57:00-06:00"
  subtype: road
  road:  # The `road` property is deprecated and will be removed in the 2024-07 release
    lanes:
      - value:
          - direction: forward
          - direction: forward
      - during: Mo-Fr 15:00-18:00
        value:
          - direction: forward
          - direction: forward
          - direction: forward
          - direction: forward

A list of lane 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.