Decide: should `Location.altLabel` reach the gazetteer lookup when `prefLabel` is absent? (v1.1 parity gap, altLabel half)

[cody-seibert-gsa]

Code repo: GSA/datagov-harvester

Problem

Location.prefLabel / altLabel never reach the gazetteer lookup, so a named-place spatial value that would resolve under v1.1 resolves to NULL under v3.0.

Update 2026-09-10: PR #925 fixed this for prefLabel. The altLabel half described below is still open.

_unwrap_location() (general_utils.py:1374) now falls back to a Location's prefLabel via the new _extract_pref_label() helper (general_utils.py:1354) when no element in the input has usable geometry/bbox/centroid. That string flows into translate_spatial() (general_utils.py:1402) and on into its existing dbi.get_geo_from_string() gazetteer lookup — the same path a v1.1 plain string takes.

_extract_pref_label() only reads prefLabel, though. It has no fallback to altLabel, so a Location with altLabel but no prefLabel anywhere in the input still returns None and resolves to NULL, exactly as before PR #925.

Input	Result	Gazetteer lookup attempted
"California" (v1.1 plain string)	✅ California polygon	['California']
{"@type": "Location", "prefLabel": "California"} (v3.0)	✅ California polygon (fixed by #925)	['California']
{"@type": "Location", "altLabel": "California"} (v3.0, no prefLabel)	❌ NULL	none

So an agency that migrates "spatial": "California" to "spatial": {"@type": "Location", "altLabel": "California"} (using altLabel instead of prefLabel) still loses spatial search coverage on that record with no warning.

Current test coverage

• test_translate_spatial_location_pref_label_only_db_hit / _db_miss (tests/unit/test_utils.py) cover the now-fixed prefLabel-only case.
• test_translate_spatial_location_array_falls_back_to_pref_label_db_hit / _db_miss include an altLabel field, but only ever alongside a prefLabel on a different array element — they assert the prefLabel wins, not that a standalone altLabel resolves.
• No test exercises an altLabel-only Location (no prefLabel present anywhere in the input). That case is unhandled today.

Decision needed

• Option A — extend parity to altLabel: in _extract_pref_label() (or a renamed equivalent), fall back to altLabel when prefLabel is absent/blank, before giving up. Add a test for an altLabel-only Location.
• Option B — keep current behavior: named-place-only Locations using only altLabel stay unresolved. If kept, consider surfacing a warning so agencies relying on altLabel notice the coverage gap instead of it failing silently.

altLabel is Optional (repeatable) in the DCAT-US 3.0 Location definition; prefLabel is Recommended. It's plausible some feeds populate only altLabel for a named place, so this gap may still matter even with prefLabel parity restored.

Context

Found in #6038 (SPIKE-3), finding 4. Related to #6294/#6295 (same SPIKE) and the locations gazetteer table. prefLabel half resolved by #925 (closes #6296).