search

opencivicdata / docs.opencivicdata.org

Open Civic Data project documentation
https://open-civic-data.readthedocs.io
44 stars 33 forks source link

0005: Area versus Division #16

Closed jamesturk closed 10 years ago

jamesturk commented 10 years ago

@jpmckinney wrote:

The "Areas vs. Jurisdictions and Divisions" section conflates two questions: "Jurisdiction versus Division" and "Why we call it Division and not Area". An Area in Popolo is the same thing as a Division. There is nothing in Popolo for a Jurisdiction, and there will probably never be †. If you find it necessary to describe the difference between Jurisdictions and Divisions, that's probably best done in 0003 where Jurisdictions are introduced.

So, for the remaining question of "Why we call it Division and not Area". The justification given is "Area does (in essence) equate to Division however, and the different terminology a remnant of decisions made prior to Area being introduced in Popolo." My reasons for "area":

  1. Popolo uses the term "area" because no one calls these things "divisions".
  2. The terms division and division_id are fairly recent in OCD and not broadly deployed. It would not be expensive to switch to area and area_id.
  3. I don’t think it is overly confusing to have the property area_id have an OCD Division ID as a value; OCD-ID is an identifier scheme. As long as we treat it as such, and not talk about "OCD Divisions" as things that exist separately from their identifiers, then confusion will be avoided.
  4. There is no such thing as 95% conformance to Popolo. A spec either conforms or it does not. Using division_id makes OCD non-conformant. I don't think the argument for division_id is a persuasive reason for breaking conformance.

If area_id is adopted, this should be used in 0003 as well.

†: FYI, the reason jurisdictions will likely never be part of Popolo is that I don't think a jurisdiction actually exists distinctly from its top-level organization. I understand that, for OCD, having jurisdictions makes organizing data and APIs and writing code easier. However, from a pure modeling perspective, there's no real thing as a "jurisdiction".

@jamesturk wrote:

We can clarify this better in that paragraph, but I disagree about Area & Division being the same thing, and this is unlikely to change.

In response to specific points: 1 & 2. We actually do use the term division and have since day one, the use is integrated into other APIs that use Open Civic Data division identifiers too.

  1. I'd disagree as to whether or not it is confusing, but more importantly OCD Divisions do exist and have properties (ones that do not match the Area schema Popolo added).
  2. We have to be pragmatic and value backwards compatibility and practicality more than conformance, I think 100% adherence is unlikely especially given some fundamental differences in how Votes will be handled. If you prefer we stop using the term Popolo we can, or just give a nod to the fact that we were inspired by Popolo, but we aren't going to be adding/changing things like this for the sake of compliance.

@jpmckinney wrote:

It sounds like I need more information than I currently have, in order to evaluate the best way forward.

  1. By "no one" I meant "no one outside of people adopting OCD"...
  2. Can you point to the APIs that use OCD-IDs and specifically their use of the terms division and/or division_id?
  3. Can you describe the properties that create a mismatch between Division and Area?
  4. To my knowledge, there are no Posts using division_id (except maybe as of a week ago?) and I have yet to see a Jurisdiction using division_id (outside of my own code). Those are the two places where the division_id property is used, according to the OCDEPs. So, what backwards compatibility is being broken if those are renamed to area_id?
  5. I need you to share your feedback on votes, because that way I actually have an opportunity to integrate your feedback and make changes to Popolo so that everyone has the option to conform. If you don't tell me anything, then how can I possibly get us to a place where everyone interoperates? Popolo is not set in stone; you can make changes. But you need to share information for us to get there.

@jamesturk wrote:

2-

Google uses the term division: https://developers.google.com/civic-information/docs/v1/divisions As does OpenElections https://github.com/openelections/specs/wiki/Elections-Data-Spec-Version-2 The endpoint for divisions has been http://api.opencivicdata.org/divisions/ since it was published.

3- Since the properties are all optional, I suppose this part is manageable, but there's a mismatch in thinking between Divisions & Areas and how they relate to boundaries. Divisions do not have a boundary but instead have a relationship to a boundary with start & end times. This seems like it'd be another noncompliance point since we'd have a field w/ the (arguably) the same purpose but a different name & structure.

4- These two cases are recent enough revisions and were they the only place I'd be OK with it. I'm more concerned about us being a moving target for others, we've used the term division in our endpoints and IDs for over a year, changing things on them now just isn't practical.

5- Point well taken, we're behind on getting you that feedback but I've just asked Paul to chime in with that today.

@jamesturk wrote:

there is also at least one vendor API that is using the term division_id internally, that's less of an issue (esp. as they haven't published it yet) but worth noting

jpmckinney commented 10 years ago

2- Re: the /divisions/ endpoint, I understand that it's in production and in use and unlikely to change at this point. It uses display_name, whereas the rest of OCD would use name, so it's maybe the most "legacy" part of OCD. If this endpoint were to change its output format at a later date, perhaps that could be a time to evaluate alignment with Popolo.

3- Since the properties are all optional, I suppose this part is manageable, but there's a mismatch in thinking between Divisions & Areas and how they relate to boundaries. Divisions do not have a boundary but instead have a relationship to a boundary with start & end times. This seems like it'd be another noncompliance point since we'd have a field w/ the (arguably) the same purpose but a different name & structure.

3- The Area spec has received the least attention and feedback. I describe some planned changes in this issue. It is intended to align better with what a Division is. Here's a rough sketch, which is close to the spec for a division object:

{
  "id": "ocd-division/country:us/state:ma/place:boston/ward:1",
  "name": "Boston Ward 1",
  "geometries": [
    {
      "valid_from": "2010-01-01",
      "valid_until": "2013-12-31",
      "value": {
        ... a GeoJSON object ...
      }
    },
    ...
  ]
}

4- I would like to explore the possibility of having Post#area_id. One option is to have both area_id and division_id in the JSON with the same value. It's not super-clean, but would that be an acceptable compromise?

jamesturk commented 10 years ago

2- yeah it is the most legacy part for sure, I think the solution you proposed is the best path forward 3- this looks pretty good, I'll go comment there with a few potential caveats based on what we've seen 4- We could definitely add this to the API. That makes the most sense to me.