Add admin_level to divisions

[stepps00]

Will replace #414.

A. Expected release date

Dec 2025

Description

This change:

• adds a new admin_level field (int value) representing the division’s position in its country’s hierarchy
• sets that new field as required for top-level subtypes; country, macroregion, region, macrocounty, and county
• keeps the existing subtype schema in tact
• updates relevant examples and counterexamples
• regenerates the pydantic baseline schema files

Checklist

Checklist of tasks commonly-associated with schema pull requests. Please review the relevant checklists and ensure you do all the tasks that are required for the change you made.

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

Update the hyperlink below to put the pull request number in.

Docs preview for this PR.

[vcschapp]

We're not really consistent in the schema (especially within the divisions theme IIRC) about whether we want to start numbered sequences at 0 or 1.

My mental model is 0 is the programmer way, 1 is the regular human way. For some reason I tend toward thinking 1 is better as the starting point here, but I don't have a strong justification for it.

Why zero, or why one?

---

This value being repeated in 3 places, it probably makes sense to define it reusably in schema/divisions/defs.yaml and reuse it.

The parallel structure in the Pydantic code base would be a NewType within the divisions package named AdminLevel.

---

Can we be a bit more precise in the documentation?

Here's a stab at it:

Integer representing this division's position in its country's administrative hierarchy, where
lower numbers correspond to higher level administrative units.

In Overture data releases, this value is equal to the number of ancestor features in the
division's primary hierarchy (the one defined by following `parent_division_id`). Thus, a
country always has an `admin_level` of 0, a region has an  `admin_level` of 1, while further
subdivisions have `admin_level` values greater than 1.

[jonahadkins]

we might have lost some context from the previous pr. the accepted standard admin 0/1/2/3. ideally we dont want to create or own standard that doesnt align. as noted, osm has their own which does not follow the majority of providers of boundary data

[stepps00]

Why zero, or why one?

Yeah, I think this is answered in Jonah's comment, but we're really just borrowing from the industry standard admin0/admin1/admin2 convention here.

This value being repeated in 3 places, it probably makes sense to define it reusably in schema/divisions/defs.yaml and reuse it.

A more recent commit does just this - replaces these three values with a new entry in the defs.yaml file.

Can we be a bit more precise in the documentation?

Thanks for this! I've updated the definition of this new property using your suggestion, with a minor tweaks.

[vcschapp]

I had to think about this for a second given that it occurs on the boundary feature type, but I recognize it is right: boundaries are only meaningful at "shared" levels of the administrative hierarchy.

[stepps00]

Yep, that's correct.

[vcschapp]

I'm aligned, this seems right!

I'm clicking request changes because ... shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

[vcschapp]

@stepps00 , we just merged the pydantic branch onto dev - can you please also include the Pydantic version of your change in this PR?

[stepps00]

shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

So I'm hesitant to mark this as required for all fields. Two main reasons:

• This assumes that all divisions exist and are present in the dataset today, which isn't necessarily the case. If, for whatever reason, the theme is missing a top-level (admin1, admin2) feature, then all descendants of that feature would have incorrect (+1) admin_level values. I think we'd want to use a per-country lookup table to derive these values.
• Do things like neighborhoods and microhoods need an admin_level? Probably not - this admin_level field is helpful to top-level (above locality) features where admin levels are typically defined.. but I'm not sure we're interested in maintaining values for lower-level subtypes.

Edit: See comment below; I've set this as required for relevant subtypes.

we just merged the pydantic branch onto dev - can you please also include the Pydantic version of your change in this PR?

This should be complete in the two most recent commits in this branch.. I'll take a look at the validation failures.

[stepps00]

shouldn't admin_level be a required field on all three feature types? If it is fully derived from the level in the feature hierarchy, which I think it is, then there's no reason why every feature shouldn't have it is there?

Update: in the most recent set of commits, I've set this new field as a required property on subtypes above localadmin in the subtype hierarchy (example). Validation should now pass with a updated Pydantic baseline schema files.