Add Jurisdiction spec (Need a way to describe the attributes of a regulating agency)

[janedotx]

Is your feature request related to a problem? Please describe.

It is necessary for cities and transportation agencies to be able to designate certain geofenced areas as being legally significant. The most obvious example is delineating the boundaries of a city. We used to fulfill that need through the use of service areas, but those are being deprecated, as they mingled too many concerns together. A plain Geography is not enough, even though it is possible to annotate such an object with metadata, because the metadata can be arbitrary, and it is desirable to keep each object type as atomic as possible.

Describe the solution you'd like

A new Jurisdiction type and service need to be defined.

Is this a breaking change

• No, not breaking

Impacted Spec

This is a call for a brand new spec.

Describe alternatives you've considered

It's possible to annotate certain Geographies using GeographyMetadata, but that gives us a less clean ontology.

[janedotx]

Pull request here: #492

[quicklywilliam]

Can you clarify how this relates to Policy and the /geometries endpoint in particular? It's confusing to me that geometries is a part of Policy but Jurisdiction is a separate thing that references geometries.

[marie-x]

@quicklywilliam

Policy and Geography are presently together in the same spec because Policy was the only service that used Geography. We will be explicitly making Geography stand-alone in an upcoming PR. Apologies for not doing that first.

[jrheard]

It’s not clear to me why this problem is best solved with a new Jurisdiction spec. It seems to me that the same goal could be achieved by amending the Geographies spec. It's very possible that I'm just not understanding the actual problems that this issue seeks to solve, because there's some stuff (eg effective) in the corresponding PR that isn't described in the issue.

---

The proposed Jurisdiction spec’s README shows that one of the main purposes of this spec is to associate the string fields agency_key, agency_name, and description with a Geography.

Why not add those fields to the Geography spec, rather than making a new+separate Jurisdiction spec?

The issue says that:

A plain Geography is not enough, even though it is possible to annotate such an object with metadata, because the metadata can be arbitrary, and it is desirable to keep each object type as atomic as possible.

I don’t think that “the metadata can be arbitrary” is a compelling argument, because the Geography spec is a specification, and can clearly mandate the names+shapes of these fields.

“it is desirable to keep each object type as atomic as possible” is a reasonable argument, but I think that adding a new spec specifically just for these three string fields will greatly increase MDS’s surface area and maintenance burden for not much gain.

Under “alternatives you’ve considered”, this issue says:

It’s possible to annotate certain Geographies using GeographyMetadata, but that gives us a less clean ontology.

I’m not sure what this means 🙂

I do notice that in the proposed Jurisdiction spec’s README, there’s some discussion of the notion of time, and of the ability to see which Jurisdictions were “active” at a particular point in time. If that’s the main use case that you have in mind, could you please explain it in more detail in this issue? Thank you!

[brianngca]

Some use cases that we are calibrated to for the Jurisdictions spec:

1. Agencies need to identify and communicate special geographies (city boundaries, state boundaries, transportation corridors) where they have authority, and where the published geographies are immutable.

• Example: El Camino Real in Palo Alto: Caltrans jurisdiction, Overlaps with City of Palo Alto jurisdiction.

2. Agencies need to collaborate with one another, and also control access to read and write data based on jurisdictions
   -Example: City of Palo Alto staff can see mobility data that traverses El Camino Real, but not necessarily see data that does not cross the jurisdiction of Palo Alto

3. A user at the county level needs to count trips within the multi-jurisdictional boundaries.

• Example: A user in the City of Palo Alto needs to count of trips that occur outside of the municipal jurisdiction, but traverse the jurisdiction (ex. Along El Camino Real)

4. Enabling the ability to share policies:

• Examples:
• The City of San Jose can easily view published mobility policies from the county of Santa Clara
• The City of San Jose can inherit a mobility policy from Santa Clara County
• The city of San Jose can also concurrently define its own mobility policies

[schnuerle]

Here's a generic diagram of what's going on in Louisville (though I think it covers a lot of scenarios elsewhere). These are some of the geographies that need to be accounted for.

The most interesting to me is the 'Area of Interest' where the city wants to know trips/deployments happening outside of its own jurisdiction. It is in some ways responsible to the surrounding cities/areas since they do not have operating agreements and the devices are there because of the first city.

full size image

[johnclary]

I don't feel strongly about separating /geographies from the policy API, but I'm a bit confused by the conflation of "jurisdiction" and "geography". There seems to be agreement that a jurisdiction should be defined as a property of a geography. At least that makes the most sense to me.

Elaborating on what @jrheard has proposed, might we wrap the geography objects in some metadata that contains the properties we're trying to track? something like

# geographies.json
{
    "version": "0.4.0",
    "updated": "1570035222868",
    "data": {
        "geographies": [
            {
                "type": "municpal_boundary",
                "geography" : {
                    // GeoJSON Feature 1
                }
            }
        ]
    }
}

We could also consider using the properties attribute of the geojson spec, but I don't think this would work well with FeatureCollection types.

For my own sanity, threads on this topic can be found across these issues:

• #491: Add Jurisdiction spec (this issue)

• #474: Policy: Formalize "Municipality Boundary" discovery

• #500: Extract Geography API from Policy API

Sort-of related:

• #480: Policy-Driven Trip Events

• #556 Extend Metrics API to accommodate street segment-level metrics

[johnclary]

and it looks like there's a proposal in PR #487 to add a type property to geographies?

[brianngca]

So, I'd like to reframe what the purpose of the jurisdiction spec is, to modify this issue as originally written, and as was previously discussed on one of the city services working group calls but perhaps not yet succinctly captured in this issue:

Is your feature request related to a problem? Please describe.

City and transportation agencies need to regulate mobility within their own legal jurisdictions. Within a collection of agencies under a single MDS instance, those agencies need to coordinate and share relevant data between one another when their jurisdictions overlap for a given geographic area. The key problems to solve here are:

1. How do agencies identify their authority (geographic area, type of mobility they regulate and where, type of infrastructure they regulate and where, up-to-date-ness, etc.) to one another and to mobility operators?

2. When mobility data flows through into a multi-jurisdictional environment, such as a Municipal Planning Organization (MPO), with multiple agencies contained within, how are users and applications at the various agencies assigned permission to see relevant data for their agency, but not for data outside of their agency?

3. In the cases where agency jurisdictions overlap how should a system represent these overlaps for the purpose of allowing different types of data purview by different users.

Describe the solution you'd like

A description of an agency as a first-class, immutable object in MDS, with attributes that can describe the agency's regulatory purview by mobility mode and infrastructure type

[schnuerle]

Note that with the merged PR #582 the new Geography API is now available in the 'dev' branch. Please take a look and see how it may impact this Issue.

[schnuerle]

This Thursday is the public Working Group meeting dedicated to Jurisdictions. Besides the presentation, it may be good to have a Pull Request ready to review as well. With about 2-3 weeks left in the release, we will need community consensus and feedback and a detailed idea this week to include it in the 1.1.0 timeframe.

https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Web-conference-notes,-2020.10.29-(Joint-Working-Group-City-Services)

Tagging @brianngca (who is presenting this week), @karcass, @avatarneil, as well as @janedotx the Issue originator.

[andrearjona]

Could Jurisdictions help cities handle in the future single-fare multi-modal trips that may occur within abutting jurisdictions? I know this is not an applicable use-case for most cities right now, but I see how starting to develop this may benefit both cities and mobility operators in the future.

[brianngca]

@andrearjona Interesting. To understand a little more, what do multiple jurisdictions need to do/what do they need to know in a single-fare multi-modal trip?

[schnuerle]

Completed this with the Jurisdictions API now in MDS.