Scoping Rules (e.g. Usage/Modes in Transportation Segments)

[e-lo]

As a user who would like to categorize segments and lanes in cities such as San Francisco, I need to be able to specify requirements (and combinations) such as

• taxi
• passenger pickup/dropoff
• electric vehicles
• (stickered low-emissions vehicles, and
• differentiate between public transit usage and private buses.

My concerns are being able to:

1. define a ruleContainer which can specify the above and combinations thereof.
2. have a consistent understanding of a mode, vs vehicle vs usage

Current draft definition of mode:

schema/schema/transportation/segment.yaml

Lines 98 to 105 in 874ca44

	mode:
	description: >-
	Enumerates possible travel modes. Some modes represent groups
	of modes.
	type: string
	enum: [ motorVehicle, car, truck, motorcycle, foot, bicycle, bus, hgv, hov, emergency ]
	"$comment": >-
	motorVehicle includes car, truck and motorcycle

Concerns:

• as defined, this is a muddy combination of vehicle (e.g. bus) and usage (e.g. hov2)
• its unclear to me how I would define a link as being accessible to a van which is used for public transit.
• its unclear to me how I would define a link that is accessible to public transit buses, but not private buses.
• additional specifications such as taxi or tnc or commercial vehicle (which doesn't have to be a truck) could be added...but it isn't clear if that should be here or as a usage option.
• additional vehicle types such as electric vehicle could be defined, but it isn't clear if this should be here or in a vehicle type within ruleContainer

Current draft definition of usageOption:

schema/schema/transportation/segment.yaml

Lines 325 to 333 in 874ca44

	usageOption:
	description: describes reason for which a person or entity travelling on the transportation network is using a particular location
	type: string
	enum:
	- asCustomer
	- atDestination
	- toDeliver
	- toFarm
	- forForestry

Concerns:

• Confused about if toDeliver includes to pick something up as well? Does this include picking up and dropping off passengers?
• I'm not sure what atDestination means?
• Unclear about the use case for Farm or Forestry? Are there designated farm- or forestry-use only facilities that wouldn't be covered by a private designation? Or is the nuance significant/important? (note this is less of a concern for me, but was confusing in trying to figure out what the pattern was for having something as a usageOption)

Current draft definition of recognizedOption:

schema/schema/transportation/segment.yaml

Lines 334 to 342 in 874ca44

	recognizedOption:
	description: describes the status of the person or entity travelling as recognized by authorities controlling the particular location
	type: string
	enum:
	- asPermitted
	- asPrivate
	- asDisabled
	- asEmployee
	- asStudent

Concerns:

• recognized official options such as (clean air vehicle decals are likely local in nature but have significant effects on usage of the transportation network

Current draft definition of ruleContainer:

schema/schema/transportation/segment.yaml

Lines 511 to 540 in 874ca44

	ruleContainer:
	description: >-
	Properties that allow defining rules from environmental and subjective scoping properties .
	type: object
	properties:
	when:
	description: describes a set of condition
	type: object
	allOf:
	- "$ref": "#/$defs/propertyContainers/modesContainer"
	- "$ref": "#/$defs/propertyContainers/duringContainer"
	unevaluatedProperties: false
	properties:
	using:
	type: array
	items:
	"$ref": "#/$defs/propertyDefinitions/usageOption"
	recognized:
	type: array
	items:
	"$ref": "#/$defs/propertyDefinitions/recognizedOption"
	vehicle:
	type: object
	properties:
	axleCount:
	"$ref": "#/$defs/propertyDefinitions/relationalExpression"
	length:
	"$ref": "#/$defs/propertyDefinitions/relationalExpression"
	weight:
	"$ref": "#/$defs/propertyDefinitions/relationalExpression"

[vcschapp]

Thank you for diving into the transportation schema in such detail!

As an initial baby step in the right direction, I'm working on an overhaul of the Transportation documentation that I hope will add a lot more detail and hopefully will tackle some of the questions you have raised here. There will be sub-pages dedicated to Scoping Properties (recognized, using, and so on) and Travel Modes which I hope will at least make some of the design scheme clearer.

The work-in-progress docs PR is available here, and I'm hoping to have it done and ready for final review by the end of today: #14.

Once those docs are done, I think there will still be some outstanding questions and issues to discuss within your above comment - mind if I circle back next week to keep the discussion going?

[vcschapp]

@e-lo Would you be willing to check out a draft of some changes to the Transportation schema docs I've been working on?

The draft really elaborates on a lot of the concepts like scoped properties, rule-based properties, and when you would use which property. It's not perfect by any means, but I'm wondering if it answers some of your questions and/or leaves you with a different set of questions at the end?

This is a link to the draft docs: https://dfhx9f55j8eg5.cloudfront.net/pr/14/themes/transportation/

[e-lo]

I (finally) got around to reviewing the updated documentation – in particular the scoping of rules. While some things are much clearer, I'm still scratching my head about some of it. In particular for the combination of scoping and rule evaluation algorithm

[e-lo]

The description here is MUCH cleaner and obvious about the expected behavior 🙏

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.

...but I'm concerned about how difficult it will be to at a glance evaluate the intersection of all of these rules in the native data format without tooling and there may be a tendency to just "tack on" a rule at the end b/c it will trump them all w/out carefully curating them. Perhaps that concern is unwarranted and the point of this is to let the 💻 🧠 do their thing and not worry about 🧑‍🦱 🧠 ?

[e-lo]

Add on to this – how would/could additional 'overlays' of information provided on top of overture interact with this? I'm thinking about wzdx or CDS as layers that you would want to be interoperable.

[e-lo]

❓ It's still not clear what the evaluation rule is for parent/child relationships such as road and lanes. I would assume that the parent is the default and any property under that can be additionally scoped based on a rule? I think an example (i.e. a peak-hour HOV or HOT lane) would be really useful here.

[e-lo]

A reference implementation of the rule evaluation either in pseudocode or as a js or python function as well as some sort of viewing/evaluation tool could go along way to providing clarity and alleviating concerns brought about by 🧑‍🦱 🧠 limitations.