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:
venue— named point/area where a family may remember an event, e.g. holiday park, attraction, museum, zoo, campground, stadium.locality— neighborhood, village, suburb, settlement, named local area below city/town scale.city— city/town/municipality-level label.geographic_area— named natural/cultural area such asEifel, island, valley, mountain area, park/forest region, or travel area.admin_region— state/province/region/land/county-like administrative label.country— country-level label.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.
venueandgeographic_areaquality 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.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference