1 ADR 0033 geonames provider mapping validation gate
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0033: GeoNames Provider Mapping Validation Gate

Status: accepted Date: 2026-05-22

Context

ADR 0025 defines the normalized place hierarchy consumed by product features: venue, locality, city, geographic_area, admin_region, country, and fallback. GeoNames is the likely first local provider, but its feature classes/codes and data quality may not map cleanly to all levels, especially venue and geographic_area.

This cannot be resolved honestly by architecture alone. It needs empirical validation against sample GeoNames extracts and known family-memory title examples.

Options Considered

Option Summary Benefits Costs / Risks
A. Declare GeoNames sufficient Assume mapping works for all ADR 0025 levels Fast planning False confidence; poor titles later
B. Drop weak levels now Only support city/region/country from GeoNames Honest and simple Gives up on desired venue/geographic-area titles too early
C. Empirical mapping gate Define candidate mapping, test sample extracts/examples, then decide supported levels Honest, incremental, evidence-based Requires validation work before production tasks
D. Switch to OSM/POI first Use richer provider immediately Better venue potential Heavier data/import complexity before GeoNames is tested

Decision

Use an empirical GeoNames mapping validation gate before production reverse lookup tasks.

The first implementation/research slice should:

  1. define an explicit candidate mapping from GeoNames feature classes/codes into ADR 0025 normalized levels;
  2. import a small fixture plus at least one real country/region extract relevant to Christian's expected data, e.g. Denmark and/or Germany;
  3. test known coordinates/envelopes for examples such as city, admin region, country, geographic area, and venue-like/title examples;
  4. measure whether GeoNames can support each normalized level with acceptable quality;
  5. mark levels as supported, experimental, or unsupported_for_provider for the GeoNames provider profile;
  6. ensure automatic album title generation degrades gracefully when a requested level is unsupported and records capability provenance when a feature-specific title policy uses an experimental level.

Production tasks should not assume GeoNames provides good venue or geographic_area labels until this validation passes for those levels. City/admin-region/country may be implemented first if they validate earlier.

The selected next-step GeoNames scope is intentionally curated rather than all feature codes. It includes A.ADM1 through A.ADM4 because those levels belong to a real administrative hierarchy and can support common-ancestor title selection. For these administrative levels, Memories may derive approximate coverage polygons from descendant toponyms and sibling partitioning as non-authoritative title-selection evidence. This derivation must not be applied to non-administrative classes (P.*, L.*, T.*, H.*, S.*) because those classes do not form a strict containment hierarchy.

GeoNames point-derived synthetic buffers are search aids, not proof that a label honestly contains an album candidate. In particular, regional automatic album titles must not use a centroid-nearest populated place such as Holzerath when child/event anchors indicate a multi-place trip.

Capability flags have distinct meanings:

  • supported: feature code may use the level as a normal title candidate for the validated scope.
  • experimental: feature code may use the level only when the feature-specific title policy accepts the quality tradeoff, records capability provenance, and avoids stronger precision claims.
  • unsupported_for_provider: feature code must degrade to another level/provider/fallback.

Consequences

Positive

  • Avoids false precision in automatic album titles.
  • Keeps GeoNames as a practical first candidate without overpromising venue/toponym quality.
  • Produces concrete provider-profile capability metadata that Admin/UI/title generation can use.
  • Leaves room for future OSM/POI or user-authored labels for weak levels.

Negative / Costs

  • Adds a validation slice before broad implementation tasks.
  • May reveal that GeoNames is only good enough for city/region/country, requiring fallback or another provider for venues.
  • Requires curated test coordinates/envelopes and expected title behavior.

Revisit Triggers

Revisit this decision if:

  • GeoNames mapping proves obviously sufficient or insufficient and the provider profile can be simplified.
  • Another local provider becomes the first implementation target.
  • User-authored favorite places become the primary source for venue/locality labels.