1 ADR 0025 normalized place label hierarchy
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0025: Normalized Place Label Hierarchy

Status: accepted Date: 2026-05-22

Context

ADR 0022 defines a provider-neutral reverse place lookup boundary, ADR 0023 selects PostGIS storage/indexing, and ADR 0024 selects operator-installed country/region gazetteer imports. The remaining normalization question is what place hierarchy product features should consume.

GeoNames, OSM-derived datasets, user-authored favorite places, and future online providers do not share identical place types or hierarchy semantics. Automatic album titles need a narrow, understandable place label such as Landal Sonnenberg, Trier, Eifel, Rheinland-Pfalz, or Germany, but the product should not leak provider-specific feature classes into album/search/title logic.

This decision needs to be small enough for first implementation while leaving room for provider-specific provenance and later richer geometry.

Options Considered

Option Summary Benefits Costs / Risks
A. Provider-native taxonomy Product code consumes GeoNames/OSM/provider classes directly Fast for first provider; preserves detail Locks features to provider semantics; hard to replace/migrate
B. Very small hierarchy Normalize only city/region/country/fallback Simple and portable Too weak for desired automatic album titles like venues/toponyms/geographic areas
C. Practical provider-neutral hierarchy Normalize to a bounded set: venue, locality, city, geographic area, admin region, country, fallback Good enough for titles; provider-replaceable; inspectable Some provider-specific nuance is lost or only kept as provenance
D. Full ontology Model rich global place ontology with many subclasses Flexible and precise Over-engineering; hard migrations; false precision

Decision

Use a practical provider-neutral hierarchy for product-facing place labels:

  1. venue — named point/area where a family may remember an event, e.g. holiday park, attraction, museum, zoo, campground, stadium.
  2. locality — neighborhood, village, suburb, settlement, named local area below city/town scale.
  3. city — city/town/municipality-level label.
  4. geographic_area — named natural/cultural area such as Eifel, island, valley, mountain area, park/forest region, or travel area.
  5. admin_region — state/province/region/land/county-like administrative label.
  6. country — country-level label.
  7. fallback — approximate/generated label when no trustworthy provider label fits.

Each PlaceNameCandidate may include:

  • normalized level from the hierarchy above;
  • display name;
  • optional hierarchy components: locality, city, admin region, country;
  • provider/source/dataset version;
  • provider-native ID/class/raw metadata for provenance/debug/export only;
  • geometry or centroid/bounds where available;
  • geometry source/authority where relevant, e.g. official/provider geometry, derived non-authoritative administrative coverage, or point-derived synthetic search aid;
  • fit/distance/prominence/population/rank signals where available;
  • language/name variant metadata;
  • attribution requirements.

Product logic such as automatic album title generation, search facets, and visibility decisions must use normalized fields. Provider-native fields are allowed for audit/debug/export and provider-specific reprocessing, but not as the product contract.

Geometry attached to a normalized candidate is not automatically authoritative. For example, a GeoNames point-derived buffer around a populated place is useful for search expansion but must not prove that a regional album belongs to that place. Conversely, administrative levels from a real hierarchy may provide derived non-authoritative coverage geometry for title selection when provenance records how it was derived.

Consequences

Positive

  • Supports the title hierarchy Christian wants without hardcoding GeoNames or OSM semantics.
  • Keeps first implementation bounded and inspectable.
  • Allows later providers to map into the same contract while retaining native provenance.
  • Gives automatic albums a clear fallback order from narrow to broad.

Negative / Costs

  • Some provider-native nuance will be flattened.
  • Mapping quality becomes provider-specific work and needs tests.
  • venue and geographic_area quality may be weak with GeoNames alone.
  • Future features may need additional subtypes, but those should be added deliberately with migration/export impact considered.

Revisit Triggers

Revisit this decision if:

  • GeoNames or another first provider cannot map usefully into these levels.
  • Automatic album titles frequently choose misleading levels.
  • Search/Places needs finer distinctions such as address, postal code, POI category, protected area, or route.
  • A future provider adds high-value geometry/category data that should become part of the normalized product contract.