Design and implement dataset-level tags

[cmbz]

Overview

This issue tracks design and implementation work for a new feature enabling dataset owners to create dataset-level tags, similar to file tags (Dataverse Guides: File Tags)

Requirements

• Dataset-level tags do not appear on the front page
• Collection owners can define and restrict a set of dataset tags within their collection

Examples

Kaggle Dataset Tags
Tags on the right hand sidebar

Hugging Face Dataset Tags
Tags at the top

[rtreacy]

Design Doc: Dataset-Level Tags

• Issue: IQSS/dataverse-pm#589
• Epic: IQSS/dataverse-pm#579 — CAFE Y5: User-Supplied Metadata and Annotation
• Related: IQSS/dataverse-pm#588 — collection-level tags (shares the "collection owner defines/restricts an allowed set" mechanism; see Relationship to #588)
• Status: Draft / pre-decision
• Author: TBD
• Date: 2026-07-10

1. Background

#589 asks for a feature enabling dataset owners to create dataset-level tags, modeled on the existing file-tags feature, with the twist that collection owners — not dataset depositors — define and restrict which tags are available within their collection. This is structurally the mirror image of #588 (collection-level tags): #588 is about tags on the collection itself (or the vocabulary it defines — see #588's open question 1), while #589 is about tags applied to datasets, with the vocabulary still governed at the collection level.

As with #588, there is no generic reusable tag entity in the codebase today. The closest precedent remains DataFileCategory (entity + parent join + free-text name, with :FileCategories supplying only UI-suggested defaults, not enforcement) and ControlledVocabularyValue (admin-defined allowed-value sets, but hard-wired to specific DatasetFieldTypes, not a standalone tag mechanism).

2. Goals

• Dataset owners (depositors) can apply tags to their dataset.
• Collection owners can define and restrict the set of tags available for use on datasets within their collection.
• Dataset-level tags do not appear on the front page.
• UI presentation modeled on examples like Kaggle (sidebar) or Hugging Face (top-of-page) — see §7.

3. Non-Goals

• Free-form, unrestricted per-dataset tagging with no collection-level governance — the issue explicitly calls for collection owners to restrict the set, so this is not simple free-text like dataset keywords.
• Collection-level tags themselves — tracked in Design and implement collection-level tags #588.
• Overlap with the existing citation metadata keyword field — see §8 for why these should likely stay distinct.

4. Open Question: Is the "restriction" the same mechanism as #588's vocabulary?

If #588 resolves toward its "vocabulary-defining" reading (collection defines a tag set applied to child objects), then #589 may simply be the dataset-facing half of the same system, not a separate feature. If #588 instead resolves toward "self-describing" (collection tags only describe the collection, not sub-objects), then #589 needs its own independent vocabulary-restriction mechanism built from scratch.

Recommend resolving #588's open question first (already flagged as its own §1) since it determines whether #589 is a from-scratch build or a thin extension. This doc assumes the shared-mechanism outcome as the working default, since it is both simpler overall and matches the literal wording of #589 ("collection owners can define and restrict a set of dataset tags within their collection" — the collection is explicitly the locus of definition, not the dataset).

5. Requirements (from issue, restated)

Requirement	Source	Notes
Dataset owners can create/apply dataset-level tags	#589	"Create" vs. "apply an existing collection-approved tag" is ambiguous — see §6
Dataset tags do not appear on the front page	#589	Same Solr indexing/facet question as #588 §8
Collection owners can define and restrict a set of dataset tags within their collection	#589	Implies the same allow-list mechanism as #588
UI inspiration: Kaggle (sidebar) / Hugging Face (top)	#589	Not a hard requirement, just visual precedent — needs an actual UX decision

6. Proposed Data Model (draft — needs review, pending §4)

• If shared with Design and implement collection-level tags #588: a single CollectionTag-style entity (vocabulary, owned by Dataverse) plus a join table associating tags with Dataset rows (mirroring FileMetadata_DataFileCategory's join-table pattern), rather than a second parallel entity.
• If independent: DatasetTag entity — id, label, dataset_id (FK), plus a separate CollectionAllowedDatasetTag table scoping which labels a given collection permits.
• Open question: can a depositor request/create a brand-new tag label (subject to collection owner approval), or can they only pick from an already-approved list? The issue's wording ("dataset owners create... collection owners restrict") suggests depositors might propose new tags that collection owners then curate — analogous to a moderation queue — but this is not explicit. Needs stakeholder confirmation; materially changes the workflow (self-service picklist vs. approval queue).
• Open question: scope to Dataset (persistent across versions) or DatasetVersion? Recommend Dataset-level, consistent with the recommendation in the Support user-supplied dataset comments #580 doc for comments, unless there's a reason tags should be versioned.

7. UI / UX

• Two precedent styles cited in the issue: Kaggle's sidebar tag list vs. Hugging Face's top-of-page tag row. Needs an actual design decision rather than defaulting to one; recommend involving the frontend team (this is presumably an SPA feature, though the issue doesn't explicitly say so the way Support user-supplied dataset comments #580 does — confirm SPA-only vs. JSF scope explicitly, since it wasn't stated).
• Tag application UI needs to reflect §6's approval-queue-vs-picklist decision — a picklist (typeahead/autocomplete against the collection's allowed set) is straightforward; an approval queue requires a moderation UI for collection owners.

8. Relationship to Existing Metadata

The citation metadata block already has a keyword compound field (keywordValue, keywordVocabulary, etc. in citation.tsv), which is dataset-level, free-text (or vocabulary-linked), and already exported/harvested via DDI/DataCite/etc. This is functionally adjacent to "dataset tags" and worth an explicit design decision:

• Keep dataset tags entirely separate from keyword (tags = lightweight, collection-governed, front-page-excluded; keywords = full metadata, exported, discoverable) — recommended, to avoid conflating a lightweight community-facing feature with the formal metadata/export pipeline.
• Document this distinction clearly in the design doc and user-facing guides once decided, so depositors and collection owners aren't confused about which field to use for what.

9. Relationship to #588

Both features need: (1) a collection-scoped tag vocabulary, (2) a way for collection owners to restrict/define allowed values, (3) front-page exclusion in search/indexing. Recommend sequencing #588's design first and building one shared mechanism, with #589 as an incremental extension applying that mechanism to datasets rather than (or in addition to) collections themselves — avoids building the restriction logic twice. See #588 doc §9 for the same recommendation from the other side.

10. Permissions Model

• Define/restrict the vocabulary: collection-level admin permission (same actor as Design and implement collection-level tags #588's vocabulary definer).
• Apply a tag to a dataset: dataset depositor / editor permission — presumably the same permission level that already allows editing dataset metadata.
• Open question: per §6, if new tags can be proposed by depositors pending collection-owner approval, that introduces a third permission tier (propose vs. approve vs. apply-only) not yet accounted for.

11. Search / Indexing Implications

Same as #588 §8 — "does not appear on the front page" needs a concrete decision about Solr indexing/faceting: excluded entirely from search, or indexed but not shown as a default facet. Recommend resolving both #588 and #589's indexing behavior together for consistency, since they're likely to share indexing code.

12. API Design (sketch)

• GET /api/datasets/{id}/tags — list tags currently applied to a dataset.
• POST /api/datasets/{id}/tags — apply a tag (validated against the collection's allowed set).
• DELETE /api/datasets/{id}/tags/{tagId} — remove a tag from a dataset.
• Collection-level vocabulary management endpoints likely shared with/identical to Design and implement collection-level tags #588's (GET/POST/DELETE /api/dataverses/{id}/tags), per §9.

13. Migration / Rollout

• If built as a shared mechanism with Design and implement collection-level tags #588 (§9), one Flyway migration covers both features; if independent, a second migration is needed for DatasetTag/CollectionAllowedDatasetTag.
• Consider a per-install or per-collection opt-in setting, consistent with Design and implement collection-level tags #588's rollout approach.

14. Open Questions Summary

1. Is this the dataset-facing half of Design and implement collection-level tags #588's shared mechanism, or an independent build? (§4 — blocks data model)
2. Can depositors propose new tags for collection-owner approval, or only pick from an already-approved list? (§6, §10)
3. Are tags scoped to Dataset or DatasetVersion? (§6)
4. Sidebar (Kaggle) vs. top-of-page (Hugging Face) placement — and is this SPA-only or JSF too? (§7)
5. Should dataset tags be kept fully distinct from the existing citation keyword metadata field, and how is that distinction documented for users? (§8)
6. Are tags searchable via advanced search despite front-page exclusion? (§11, mirrors Design and implement collection-level tags #588's same question)

15. Out of Scope / Future Work

• Tag-based dataset discovery/browse pages (e.g., a dedicated "browse by tag" view) — not requested by the issue, but a natural follow-on once the mechanism exists.
• Cross-collection shared tag vocabularies — the issue scopes restriction to "within their collection," so cross-collection vocabularies are explicitly out of scope for now.