[WIP] Update divisions subtype naming convention

[stepps00]

Major change release plan

A. Expected release date for this MAJOR change

Dec 2025

B. Related MINOR change steps

TODO

C. Public documentation and messaging plan

• Theme guide updates
• Documentation in the release notes

Description

The divisions theme has discussed moving to an adminN (admin0, admin1, admin2, admin3) subtype naming convention for top-level divisions, while keeping more semantic subtypes (locality and below) intact.

Some rationale for this change:

• Every top-level division would fit cleanly into a numbered level.

• Easier to query and maintain, users understand what admin1 or admin2 mean and these terms are interoperable with other open administrative datasets (geoBoundaries partnership?).

• Frees up words like “region” for other feature types.

• Works for any country or future level without redefining new types for existing features.

Proposed mapping

Existing subtype	New subtype
country	admin0
dependency	admin0
macroregion	N/A
region	admin1
macrocounty	N/A
county	admin2
localadmin	admin3
locality	locality
borough	borough
macrohood	macrohood
neighborhood	neighborhood
microhood	microhood

Notes:

• Both country and dependency records would be classified as admin0. Dependencies would maintain a parent_division_id value equal to the GERS ID of the administering country.
• The theme does not (and has not) maintained macroregion or macrocounty features. These subtypes would not match one-to-one to a new adminN subtype
• This change simply renames the subtypes - it will not impact what features appear at these subtype levels - ie all regions become admin1, all localadmin become admin3, etc.

All references and examples / counterexamples have been updated with these new adminN subtype names.

Reference

TODO

Testing

TODO

Checklist

1. Add relevant examples.
2. Add relevant counterexamples.
3. Update any counterexamples that became obsolete. For example, if a counterexample uses property A but is not intended to test property A's validity, and you made a schema change that invalidates property A in that counterexample, fix the counterexample to align it with your schema change.
4. Update in-schema documentation using plain English written in complete sentences, if an update is required.
5. Update Docusaurus documentation, if an update is required.
6. Review change with Overture technical writer to ensure any advanced documentation needs will be taken care of, unless the change is trivial and would not affect the documentation.

Documentation website

[Docs preview for this PR.](https://dfhx9f55j8eg5.cloudfront.net/pr/<PUT THE PR # HERE>)

[tijptjik]

Apologies in advanced if this is ignorant, but wouldn't it be more consistent to remove borough in the New subtype for similar reasons adminN is preferred over (sometimes) incorrect labeling of areas given the de facto local nomenclature?

"Borough" is quite a rare administrative division and is currently already expressed as a marcohood or neighborhood for the New York and London boroughs - in fact it's not used for any division subtype, so removing it wouldn't result in the need to any division needing to be reclassified.

See 413 for details.

[vcschapp]

What's the underlying motivation for this change, and are you aware of some of the design choices in having named subtypes?

---

• One of the nice parts of the current design is that the terms country and region are used consistently in various contexts (country and region subtypes have a corresponding country and region property or column)...
• As well there's just general consistency: are subtypes descriptive names, or are they numbers?
• And the "admin level" abstraction can be derived today from the primary hierarchy or following the parent_division_id tree to the root (which can be written up in SQL).

---

Motivation: Is the main motivation to give people a simple "1, 2, 3..." level abstraction?

Like I said this can be derived from the data today, but if we view that as too user-unfriendly, may I suggest the alternative of just adding a rank property that has the 1-based level of the feature in the primary hierarchy tree?

[vcschapp]

One extra thought: the advantage of a rank or similar column is that it contains an integer value, and you have more ready query options with integers.

e.g.

WHERE rank >= 2

Is a lot easier than:

WHERE subtype IN ('admin2', 'admin3', 'admin4', 'admin5', 'admin6')

Or

WHERE CAST(REGEXP_EXTRACT(subtype, 'admin(\\d+)') AS INTEGER) >= 2

[vcschapp]

It was noted in the schema meeting this morning that:

1. Calling things "admin0", ... "admin3" is an industry standard.
2. Dependencies like Puerto Rico and Guam are "admin0" even though they conceptually are subject to the administration of another country that is also going to be "admin0".

For #1, for my education it would be super helpful to understand the players who do (and do not) use this scheme. (We know that WOF and OSM do not.)

For #2, this seems odd to a layman like me.

• Why is Puerto Rico "admin0" if it is a "child" of the USA which is also "admin0"?
• Since it is not a country, and this PR is proposing to delete the information that it is a dependency, are we sure the benefits of the change make up for the reduction in information content?

[vcschapp]

What's the underlying motivation for this change, and are you aware of some of the design choices in having named subtypes?

• One of the nice parts of the current design is that the terms country and region are used consistently in various contexts (country and region subtypes have a corresponding country and region property or column)...
• As well there's just general consistency: are subtypes descriptive names, or are they numbers?
• And the "admin level" abstraction can be derived today from the primary hierarchy or following the parent_division_id tree to the root (which can be written up in SQL).

Motivation: Is the main motivation to give people a simple "1, 2, 3..." level abstraction?

Like I said this can be derived from the data today, but if we view that as too user-unfriendly, may I suggest the alternative of just adding a rank property that has the 1-based level of the feature in the primary hierarchy tree?

Uses of region column to contain the principal subdivision code:

• https://github.com/OvertureMaps/schema/blob/dev/schema/defs.yaml#L24 (Used in Places)
• https://github.com/OvertureMaps/schema/blob/dev/schema/divisions/division.yaml#L99-L117

[TristanDiet-TomTom]

The Industry standard feels very much tailored on the USA 'official' hierarchical structure:
country > state > county > 'local admin' (aka 'go figure')

Also the proposed mapping reflects this perception: county maps to an admin2.
This might be different for counties in other countries.

Many other countries have a different official structures, e.g.
country > province > city > district

or sometimes a non-formal structure (dare I say, non-administrative) of
country > province > city > neighborhood.
This is not something you want to show as default hierarchy, but it is good to know that your neighborhood 'belongs' to a certain city.

The latter is what "hierarchies" wants to achieve.
The choice was at the time made to make the subtype based on the opinionated place type categorization of OSM.
At best these types give an idea of what a division represents, but it did not try to represent any administrative level let alone a hierarchical index level.

If 'the want' is to have administrative levels more clear, it feels like introducing a numeric 'level' property, could be more target leading.
This allows for more variations between countries while still keeping the approach globally consistent.

Right now I'm worried that it will not even fulfill worldwide that need, as there are some countries which have more levels between country and 'local_admin'.

[stepps00]

Thanks everyone for all the feedback here — super helpful. A few comments after reading through everything:

1. I agree there’s value in the existing subtype nomenclature. The points about subtypes being descriptive, consistent with country/region, and tied into other schema pieces do make sense.

2. A numeric admin_level field, like @vcschapp suggests feels like a decent middle ground. This addresses the main goals without changing the subtype model:

• it gives users a simple, universally queryable hierarchy (ex: WHERE admin_level >= 2)
• aligns better with World Bank, GeoBoundaries, etc. datasets with that adminN system
• avoids the dependency confusion (Puerto Rico/Guam both becoming admin0)
• to @TristanDiet-TomTom 's point, it works better for countries with deeper or non US-shaped hierarchies
• preserves the consistency/nomenclature of named subtypes

This is a different approach than what is in this pull request and what was discussed with the theme, though. So @jonahadkins and @sasastanojkov, curious to hear your thoughts.

3. For context, the motivations behind the original proposal were:

• easier mapping to external providers/future collaborators
• simpler way to understand where the division fits within the country's administrative hierarchy
• freeing up “region” for future non-administrative region work

I think these can still be achieved with 1. a new admin_level field and 2. a new subtype addition (colloquial_region or similar) or re-use region with a new class value.

4. Either way, we should correct subtype mappings for each country. To @tijptjik's point, subtypes like macroregion, macrocounty, borough, etc. don't have associated features today -- though these should exist if we want to match the subtype descriptions.

5. A potential path forward:

• keep the existing subtype schema
• add a new admin_level (int) representing the division’s position in its country’s hierarchy
• populate admin_level across the dataset.
• clean up subtype mappings for each country (ex: we should have boroughs, but don't today)
• document how admin_level interacts with 3P mappings so consumers get a clear, consistent hierarchy abstraction.

[jonahadkins]

For #1, for my education it would be super helpful to understand the players who do (and do not) use this scheme. (We know that WOF and OSM do not.)

Mapbox Boundaries, geoBoundaries, Natural Earth, World Bank, GADM, Here Maps, Field Maps (via United Nations)

OpenStreetMap uses the nomenclature "admin level", but starts with countries at 2.

from their rationale: admin_level=2 through admin_level=10 allow for different administrative subdivision schemes to be handled in a consistent way by data consumers. The use of a numbering scheme rather than words for the values helps avoid confusion due to different terminology used in different countries.

although it then says: data consumers should take care when interpreting values of this key. While admin_level=2 is almost always a de-facto independent country, and admin_level=4 is usually equivalent to a "province", higher values vary in meaning between countries.

The choice was at the time made to make the subtype based on the opinionated place type categorization of OSM.
At best these types give an idea of what a division represents, but it did not try to represent any administrative level let alone a hierarchical index level.

no clue why the say " 2 is almost always a de-facto independent country", because they seem to be the only ones doing it. Even though we use OSM for borders and placenames at present, we should strive to not use their classification terms, like all the providers mentioned above.

adding a rank property that has the 1-based level of the feature in the primary hierarchy tree

in the cartographic sense, rank infers prominence, which is what we call it https://github.com/OvertureMaps/schema/blob/dev/schema/defs.yaml#L330

admin level provides a way to normalize across all countries without mixing terminology. admin level is a numbered hierarchy, but the use of subtype in our hierarchy mixes terms across countries for ex:

• Greece + Somalia call their admin level 2 a "region"
• Lithuania, Liberia, Kenya call their admin level 1 a "county"
  .

after further discussion with @stepps00 , i too have "flipped" toward making this a stand-alone column. the original intent in a mixed approach was admin 1-3 are standard ways to refer to country-state-county while everything below that is up for debate. for those levels we should take another pass at those as Stephen mentions above (4).

ps: region still feels wrong imo - what's a region, who knows! 1, [2] many organizations define this as a grouping of administrative areas , and yes some countries define a region as an administrative area. i too have been raked over the coals for trying to define them. we can discuss more in #360

[vcschapp]

• WHERE admin_level >= 2

Quick note, IMHO admin_level is probably a better name than the one I'd suggested (rank). It seems important that the word admin and level be included to achieve the usability goal.

[vcschapp]

OpenStreetMap uses the nomenclature "admin level", but starts with countries at 2.

I think the incredible complexity of the OSM table for boundary=administrative tells the story. This is what I was thinking of when I said OSM doesn't follow the convention.

They have country as admin_level=2 and on the country-specific table there are gaps at the very next level: many countries do not use level 3, 4, 5, ...

[vcschapp]

For #1, for my education it would be super helpful to understand the players who do (and do not) use this scheme. (We know that WOF and OSM do not.)

Mapbox Boundaries, geoBoundaries, Natural Earth, World Bank, GADM, Here Maps, Field Maps (via United Nations)

Thanks for this list. Regarding HERE, that may be true of their GIS offering (I didn't know this) but I've worked extensively with their search API over a number of years and they absolutely don't use it there. They use a field called "administrativeAreaType" whose domain of values is string names like "country", plus a taxonomy of address-level fields named "country", "state", "county", "city", "district", and "subdistrict". This can be seen in their current Geocoding and Search API Reference V7. I believe they do use a numeric ranking system in their map tiles, which makes sense, but I also believe the field name there is kind.

Incidentally, the same thing I said about HERE is true of the Mapbox search API (geocoding V6) and the TomTom search API. Obviously these are more "address use cases", but the point I'm trying to make is that there are different approaches.

I value the WOF approach for trying to build a taxonomy than can capture the whole complexity of the world and not bash it into a squeeze frame that eliminates nuance and removes information content. OTOH, I'm cognizant that sometimes a number is just easier to work with. That's why I'm suggesting the "Why can't it be both?" approach of adding a new field/property/column. ...

[vcschapp]

@jonahadkins Another interesting example is the Azure Maps search API because they actually have a "get the boundary polygon" API, Get Polygon - Search. As far as I can tell, they also use a textual rather than a numeric system. Theirs is called BoundaryResultType and the allowed values are:

It's not super obvious what "country or region" means, but of note that they do use that term at the top level.

[vcschapp]

@stepps00 RE:

• freeing up “region” for future non-administrative region work

I assume this relates to RFD 57 - Add geographical regions to the Divisions theme.

FWIW we did have a number of one-word terms that seemed to fit the bill - cluster, zone, bloc, colloquial, etc.

[vcschapp]

@stepps00

8. A potential path forward:

• keep the existing subtype schema
• add a new admin_level (int) representing the division’s position in its country’s hierarchy
• populate admin_level across the dataset.
• clean up subtype mappings for each country (ex: we should have boroughs, but don't today)
• document how admin_level interacts with 3P mappings so consumers get a clear, consistent hierarchy abstraction.

Very aligned on this.

Especially excited about the initiative to clean up the subtype mappings and get things like boroughs in. That would be a big win for usability IMO.

I like the simplicity of this:

• add a new admin_level (int) representing the division’s position in its country’s hierarchy

Can you confirm that it will satisfy the use cases you have discussed in the TF? (Since it implies that an ordinal rank admin_level is more important than the specific numbers 0-3 that were initially proposed.)

[sasastanojkov]

From my understanding this PR had as one of the goals freeing of term region. I am ok with using subtype administrative or whatever variation alongside numeric value admin_level.
I don't think we should introduce admin_levels in the same manner they exist in OSM since in that case anyone consuming the data will have one less reason to move from OSM to Overture. It is, from my point of view, and I think from Overture product of view better to normalize it.
If we just translate to admin with level 0, region to admin with level 1, ... We have clarity when creating boundaries between entities of the same level. In that sense, I am wondering what should be admin_level of dependency? Additionally, this will also impact division_boundaries. We have to be mindful that currently we have country subtype boundaries between dependencies and countries (example being border between Franch Guiana and Suriname id: 0e842914-2bc4-3e46-8d78-0af60dadb3bb)

[stepps00]

I don't think we should introduce admin_levels in the same manner they exist in OSM since in that case anyone consuming the data will have one less reason to move from OSM to Overture. It is, from my point of view, and I think from Overture product of view better to normalize it.
If we just translate to admin with level 0, region to admin with level 1, ... We have clarity when creating boundaries between entities of the same level.

Completely agree and I think the theme actually has most of what it needs to create a normalized admin_level value structure for each country.

If we just translate to admin with level 0, region to admin with level 1, ... We have clarity when creating boundaries between entities of the same level. In that sense, I am wondering what should be admin_level of dependency?

A few options worth considering:

• Both country and dependency become admin_level=0

  • The first-level division within both become admin_level=1, second-level become admin_level=2, etc.
  • The parent_division_id of the dependency would be the ID of the country
  • The division_area geometries of the country and dependency stay separate/independent of one another

• Countries become admin_level=0, dependencies become admin_level=1

  • Dependencies and regions treated equally
  • Dependencies are included in the country division_area geometry

• A new subtype is created for admin_level=0 (think empire or kingdom)

  • Both country and dependency become admin_level=1
  • The parent_division_id of the dependency and country would be the ID of the new parent subtype
  • The new parent subtype division_area boundary includes the geometry of both the country and dependency
  • 1 becomes the 'default' highest admin_level value in most cases, 0 being reserved for any country with a dependency (UK, US, Netherlands, France, etc.)