Facets show vocabulary URIs instead of human-readable labels (cross-repo)

[rdhyee]

Problem

On the Interactive Explorer, the Material / Sampled Feature / Specimen Type facets render raw vocabulary URIs as their labels:

https://w3id.org/isample/vocabulary/sampledfeature/1.0/pasthumanoccupationsite (1,059,025)
https://w3id.org/isample/biology/biosampledfeature/1.0/Animalia (188,361)

The Source facet is fine (short codes — SESAR, OPENCONTEXT, GEOME, SMITHSONIAN). Everything that comes through the SKOS vocabularies is broken.

Root Cause

The bug lives upstream of the Explorer. Sampling the wide parquet:

SELECT row_id, label, scheme_name
FROM read_parquet('https://data.isamples.org/isamples_202601_wide.parquet')
WHERE otype = 'IdentifiedConcept'
LIMIT 5;

returns:

(19401546, 'https://w3id.org/isample/vocabulary/materialsampleobjecttype/1.0/wholeorganism', NULL)
(19401547, 'https://w3id.org/isample/opencontext/materialsampleobjecttype/0.1/tile',         NULL)
(19401548, 'https://w3id.org/isample/opencontext/materialsampleobjecttype/0.1/clothing',     NULL)

So IdentifiedConcept.label already holds the URI rather than the SKOS prefLabel, and scheme_name is NULL. By the time pqg facet-summaries runs (pqg/__main__.py @ aefd465), it does:

SELECT 'material' AS facet_type, c.label AS facet_value, c.scheme_name AS scheme, COUNT(*) AS count
FROM (...) JOIN (... otype = 'IdentifiedConcept') c ON c.row_id = s.material_id

and faithfully copies the URI through into facet_summaries.parquet. The Explorer's OJS code (tutorials/isamples_explorer.qmd:119-174) renders r.value directly.

Why a Quick Fix Isn't Right

Easy options on the table:

• In-page string mangling (x.split('/').pop()): renders pasthumanoccupationsite, not Past Human Occupation Site. Loses fidelity. Doesn't help notebooks or future consumers.
• Bake labels into facet_summaries.parquet at build time only: helps the Explorer but not the wide parquet, narrow parquet, or any Python notebook that touches IdentifiedConcept.label.

Per @rdhyee on 2026-04-28: "let's do (2) properly and make sure the work we do is useful throughout our work (Quarto, and Python, etc)."

Proposed Approach: canonical `vocab_labels` artifact

Build a single, canonical lookup artifact from the SKOS vocabularies (already at https://github.com/isamplesorg/vocabularies and consumed by `vocab_tools` in `scripts/generate_vocab_docs.sh`):

`vocab_labels.parquet` (or .csv) with columns:

• `uri` (PK)
• `pref_label` (SKOS prefLabel, en)
• `scheme` (the vocabulary it belongs to)
• `definition` (skos:definition, optional but cheap to include)
• `alt_labels` (list, optional)

Hosted at `data.isamples.org/vocab_labels.parquet` (versioned + `/current/` alias, like the other parquets).

Consumers

Consumer	Use
`pqg` SQL converter	Populate `IdentifiedConcept.label` with prefLabel during PQG conversion (replaces the URI). Keep URI in a separate `uri` column.
`pqg facet-summaries`	No change needed if upstream is fixed; otherwise LEFT JOIN onto `vocab_labels`.
Explorer (Quarto/OJS)	Optional secondary lookup if we want short-term fix without regenerating wide parquet.
isamples-python notebooks	Loaded as a small DataFrame for any analysis touching concepts.
Future React / detail-panel UIs	JSON dump (`{uri: prefLabel}`) ships from same source.

Open Design Questions

1. Where does it get built? Most natural home is `isamplesorg/vocabularies` (publish prefLabel CSV alongside the TTL) or `vocab_tools` (add a `vocab labels` subcommand that emits parquet/csv). Voting weakly for `vocab_tools` since it already parses the same TTLs.
2. Multilingual? SKOS prefLabels can be tagged. Default `en`, ship one row per (uri, lang) so consumers can filter.
3. Versioning? Vocabularies are versioned in their URIs (`.../1.0/...`). Should `vocab_labels.parquet` be versioned per release of the vocabulary set, or rebuilt-on-write?
4. Fix at IdentifiedConcept-creation time vs join-on-read? Fixing at IdentifiedConcept-creation time is cleanest (every downstream consumer gets correct labels for free) but means regenerating the wide parquet. Join-on-read is incremental but proliferates the workaround.
5. Extension vocabs. The biology extension (`https://w3id.org/isample/biology/biosampledfeature/...\`) and Earth Science extension live in different repos. Need a discovery list, or each vocab repo emits its own `vocab_labels` shard and we concatenate.
6. What about `scheme_name` being NULL in current IdentifiedConcept rows? Same upstream bug; fixing prefLabel is a chance to fix scheme too.

Affected Repos

• isamplesorg/vocabularies — source of truth (TTL files)
• smrgeoinfo/vocab_tools (or a fork) — likely home for the new `labels` exporter
• isamplesorg/pqg — fix `IdentifiedConcept.label` populator in the SQL converter; possibly add LEFT JOIN to `facet-summaries` as belt-and-suspenders
• isamplesorg/isamplesorg.github.io (this repo) — Explorer consumes the corrected facets; tutorials may need a `vocab_labels` ref
• isamplesorg/isamples-python — example notebook showing how to enrich queries with prefLabels

Suggested First Step (low-risk)

Add a `vocab labels` subcommand to whichever `vocab_tools` we control that emits `vocab_labels.parquet` from a list of vocabulary TTL URLs. Publish to `data.isamples.org/vocab_labels.parquet`. Don't touch any other repo yet — that gives every consumer a stable artifact to JOIN against, and we decide the at-pipeline-time fix once the artifact exists.

cc @rdhyee — filed at your direction (2026-04-28); the Explorer fix is gated on this.

[rdhyee]

Findings while building `vocab_labels.parquet` v1 (2026-04-28)

While building the artifact, hit two real-world wrinkles that the design needs to handle. Capturing them here so they don't get lost.

1. /1.0/ URI mismatch between vocabularies and data

The vocabulary TTLs at `isamplesorg/vocabularies` declare concepts at URIs without a version segment, e.g.:

https://w3id.org/isample/vocabulary/materialsampleobjecttype/wholeorganism

But every data layer downstream uses a /1.0/ version segment:

https://w3id.org/isample/vocabulary/materialsampleobjecttype/1.0/wholeorganism

I traced this: the version segment is in the iSamples export itself, not added by pqg. Sample from ~/Data/iSample/2025_04_21_16_23_46/isamples_export_..._geo.parquet:

has_material_category → 'https://w3id.org/isample/vocabulary/material/1.0/organicmaterial'
has_context_category  → 'https://w3id.org/isample/biology/biosampledfeature/1.0/Animalia'

So the source-record convention used by OpenContext / SESAR / GEOME / Smithsonian when emitting iSamples export records bakes /1.0/ into the identifier. pqg is just propagating it. The vocabularies repo doesn't reflect this convention.

Result: a literal JOIN between facet URIs and TTL-declared URIs returns 0 rows for the 20 URIs that show up in the wide parquet. ☹️

v1 mitigation: emit dual-form rows in vocab_labels.parquet — one at the TTL-declared URI, one at the synthesized /1.0/ form — with a uri_form column tagging which is which. Consumers can JOIN against either, and the uri_form column makes the convention explicit instead of hidden.

Worth a separate issue upstream (in isamplesorg/vocabularies or as a metadata-modelling discussion): is /1.0/ a deliberate versioning convention, an accident propagated from older iSamples Central code, or something else? If deliberate, the TTLs should mint concept URIs with /1.0/. If accident, sources should drop it on next export.

2. Cross-vocabulary duplicate concept declarations

17 concept URIs are re-declared in 2-3 different TTLs with slightly different labels:

material/mineral   "Mineral "                     in material_type.ttl
material/mineral   "mineral"                      in opencontext_material_extension.ttl
material/mineral   "mineral"                      in earthenv_material_extension_mineral_group.ttl

Inherited inconsistency from independent vocabulary authoring (no coordination layer between core, OpenContext, Earth Sci, biology TTL maintainers). All 17 affected concepts are in vocabulary/material/....

v1 mitigation: dedupe — for a given URI, prefer the TTL whose URL prefix matches the concept (so vocabulary/material/... keeps the label from material_type.ttl). Drop the others, but preserve their labels in alt_labels.

Out-of-scope for v1, worth flagging

• Whether /1.0/ should live in the canonical concept URIs (vocabulary repo question)
• Whether the cross-vocab redeclarations should be cleaned up at the TTL level (vocabulary maintainers' call)
• Whether `pqg` should normalize /1.0/ → no-version (or vice-versa) at IdentifiedConcept-creation time

Both surface as design debt for the closeout phase but don't block the artifact.