Policy: Formalize "Municipality Boundary" discovery

[brianellin]

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

Several parts of MDS depend on a precise definition of the municipality boundary, however the spec doesn't offer guidance on where exactly to define or discover this important geography.

Here's the current language from the provider spec:

Municipalities requiring MDS Provider API compliance should provide an unambiguous digital source for the municipality boundary. This boundary must be used when determining which data each provider API endpoint will include.

The boundary should be defined as a polygon or collection of polygons. The file defining the boundary should be provided in Shapefile or GeoJSON format and hosted online at a published address that all providers and provider API consumers can access and download.

This can lead to inefficiencies and confusion when communicating the boundary details from agencies to providers and vice-versa. Additionally, the Policy spec states that:

No part of the geographical data should be outside the municipality boundary.

For both those reasons, formalizing the discovery of the municipality boundary seems desirable.

Describe the solution you'd like

Since the MDS Policy API already does the job of communicating important geography definitions from agencies to providers, that seems like a natural home for the municipality boundary.

Below is a proposal to represent the boundary within the existing /geographies REST endpoint and geographies.json flat file:

{
    "version": "0.4.0",
    "updated": "1570035222868",
    "data": {
        "geographies": [
            {
                // GeoJSON Feature 1
            },
            {
                // GeoJSON Feature 2
            }
        ],
        "municipality_boundary": [
            {
                // GeoJSON Feature 1
            }
        ]
    }
}

An alternate approach might be to include the municipality_boundary in the geographies dictionary directly. Would welcome other ideas/suggestions for how to formally define.

Is this a breaking change

• No, not breaking

Impacted Spec

For which spec is this feature being requested?

• policy

Describe alternatives you've considered

n/a

Additional context

n/a

[marie-x]

I have an alternate proposal that goes a little further, an API for Jurisdiction. I will be submitting it in the next week or so.

[marie-x]

@brianellin have you had a chance to review the Jurisdiction spec? PR #492

[schnuerle]

@brianellin Do you think PR #492 addresses your municipal boundary definition concerns?

[schnuerle]

Moving this to 1.1.0. Let me know if you think this should be in 1.0.0 instead with your #492 PR.

[brianellin]

Thanks @karcass and @schnuerle. I've read PR #492 and have a clarifying question:

Is the intention that each jurisdiction implicitly represents a municipality boundary, as referenced in the provider and policy specs? If so, I feel that relationship should be made more explicit.

[marie-x]

@brianellin Yes, we'll clarify the wording.

[brianngca]

@brianellin It is one of the use cases of jurisdictions that it represents a municipal boundary. More broadly though, various governing agencies that are not necessarily cities (ex In the San Francisco Bay Area, Caltrans, VTA, BART) have jurisdictions that can overlap with municipal boundaries.

[jrheard]

@brianngca thanks, that's helpful to know! In that case, how do you know - at a programmatic level, without a human having to read and understand the textual names of each Jurisdiction - which Jurisdiction is a city's municipality boundary and which Jurisdictions aren't? I've read https://github.com/openmobilityfoundation/mobility-data-specification/blob/6c6aac648fbf04e35ee9d9af186bd6050bb781f0/jurisdiction/README.md a few times and don't see this topic directly addressed there, but it's possible that I'm missing something!

[brianngca]

@jrheard For the purposes of the spec, the proposal was to just define the boundaries of the agency's jurisdiction, be it a city or another agency. As currently proposed, there isn't a non-human way to identify if the jurisdiction is specifically that of a city. I suppose the introduction of an agency_type could be a solution (off the top of my head).

The end use cases we were thinking about were: a person granting permissions to others/systems for data access; or for an analyst who needs to cut data by the view of the agency.

Happy to get your take on programmatic use case that need to be supported!

[jrheard]

Cool, that makes sense, thanks again for that clarification. It sounds to me like the Jurisdiction API wouldn't actually be a direct solution to this particular github issue (although perhaps it is and I just haven't been able to figure out how to connect the dots!)

An example programmatic use case that comes to mind is one where you want to write a program that consumes an operator's MDS Provider feed for Exampletown, and you also have access to Exampletown's Geographies API, and you want to be able to write some code that automatically detects/filters any status changes that a) appear in the operator's feed, but b) aren't located within Exampletown's municipality boundary, eg because the feed might mistakenly contain data from two adjacent cities.

Right now it's certainly possible to implement this program, but only with human intervention - you need a human being to look through Exampletown's set of published Geographies, figure out which one actually represents the Exampletown municipality boundary, and amend your program to use that specific Geography.

This is just a single contrived example, but as @brianellin points out in the issue description, the MDS spec refers to the concept of the "municipality boundary" in various places, and so I think that it would be a good idea for the spec to clearly represent this concept at a level that can be understood by code.

---

Here are a couple of ideas that have come to mind:

1. The definition of the /geographies endpoint could be modified to say that one (and only one) of the returned Geographies must include the key/value pair "municipality_boundary": true in its properties section
2. The /geographies endpoint's data payload could be modified to also include a municipality_boundary: a_geography_id key/value pair

I don't really like the first idea; IMO it would be very easy for a buggy /geographies implementation to return a list where zero or multiple Geographies have that key/value pair. The second idea seems workable to me, though!

I've put together a PR for that second approach, and would be curious to hear what the community thinks of it: #545

Alternatively, is there some third approach that people would prefer?

[brianngca]

Thanks for writing out the use case @jrheard. That makes sense.

Thinking more broadly, what if we thought about this as a type of agency. That could be represented in the jurisdictions API. I like the idea of keeping /geographies relatively agnostic so that many services could easily use it. Wondering what you think of this approach?

Types of jurisdictions could potentially include:
city_boundary
MPO
transportation_agency
etc.

[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]

@brianngca Does the new Jurisdiction proposal and the geography API solve for this issue now?

[schnuerle]

Jurisdictions should cover this as a solution. While it's in beta we can figure out what may need to change and create a new issue then. Thanks!