Replace free-form tags with a controlled vocabulary, primary category and language - #392
Merged
Conversation
`tags` is currently asked to do two jobs with opposite requirements. The website uses it to build the filter row on scverse.org/packages, which needs a small, stable, coherent vocabulary; it is also the only thing making packages findable by keyword, which needs the opposite — breadth, and a long tail nobody has to spell the same way. Serving both from one free-form field means neither works. Across 118 packages there are 259 distinct tags, 71% of them used exactly once. `single cell` and `single-cell` are separate entries, as are three spellings of spatial omics, so the filter row shows the same concept several times and pads the remainder with `python`. The website has been papering over this with a hardcoded alias map, which is invisible to the people writing the tags and silently rots as new packages arrive. Split the two jobs. `topics` is a required, closed vocabulary of 18 terms that says what a package is for, and drives the website filters. `tags` keeps its current meaning, stays free-form, and is used for search, where incoherence is harmless. Topics for the existing 118 packages were seeded from their descriptions and tags, then corrected package by package: the seeding read "annotated data matrices" as annotation, "integration testing" as integration, and missed cellxgene being a viewer. Enforcement needs no new code. `validate_registry.py` already runs `jsonschema.validate` per package, and an unknown topic produces "'foo' is not one of [...]", so contributors get the whole vocabulary at the point where they are blocked.
Member
Author
|
@grst see scverse/scverse.github.io#254 for some additional context. What is your opinion on this PR and the approach? I wonder whether we should remove free-form tags completely and only allow our controlled vocabulary. I think we could allow people that submit PRs to suggest new terms but generally nudge them to use whatever we'd already have. Thanks! |
Member
Author
|
I think this & the frontend PR are also associated with scverse/scverse.github.io#106 right? |
Contributor
|
We initially didn't control the vocabulary since we didn't know what it should contain. With >100 ecosystem packages, I think we should have a good sample of the "tag universe". Should something new be required, submitters can amend the schema in their PR. I'd just tell an LLM to collapse the currently existing topics, throw out a couple of non-descriptive ones, and enforce a controlled vocabulary in the future. |
Zethson
changed the title
topics vocabulary alongside free-form tagstopics vocabulary
…guage Follows the review: no free-form tags at all, and the vocabulary is collapsed out of the tags that already existed rather than invented. `tags` becomes a 45-term enum, folded from the 250 distinct tags in the registry, with the non-descriptive ones dropped (`python`, `single-cell`, `bioinformatics`, `utilities`, library names). `primary_category` names the one category a package is listed under. Both mirror the tutorial registry, which already solved this, so the two registries share terminology instead of inventing their own. `language` is assumed to be Python unless set, and marks the three R packages. Closes scverse/scverse.github.io#106, closes #299, closes #46.
Zethson
changed the title
topics vocabularyA JSON Schema default is documentation, not behaviour: jsonschema does not apply it, so the field stays absent from packages.json and every consumer has to reimplement the fallback. Stating it on all 118 packages costs one line each and removes that.
Zethson
commented
Aug 13, 2026
| "description": "Language a user writes code in when using the package. Assumed to be Python when omitted.", | ||
| "description": "Language a user writes code in when using the package.", | ||
| "type": "string", | ||
| "default": "Python", |
Member
Author
There was a problem hiding this comment.
We can keep this but I like things complete and explicit.
Zethson
added a commit
to scverse/scverse.github.io
that referenced
this pull request
Aug 13, 2026
scverse/ecosystem-packages#392 replaces free-form tags with a controlled vocabulary, a primary category and a language, so the normalisation this template was doing can go: the alias map, the tag counting, the `>= 3` threshold and the top-12 slice are all deleted. The chip row is now the categories actually in use, biggest first, which is stable across registry updates rather than shifting whenever a package is added. Tags filter from the cards, since 45 of them would not fit in a chip row, and non-Python packages get a language badge. Needs scverse/ecosystem-packages#392 merged and redeployed first. Until then the live packages.json has no primary_category, and the chip row renders empty.
grst
approved these changes
Aug 13, 2026
grst
left a comment
grst
left a comment
Contributor
There was a problem hiding this comment.
one small thing, otherwise LGTM
Co-authored-by: Gregor Sturm <mail@gregor-sturm.de>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes scverse/scverse.github.io#106, closes #299, closes #46.
tags— 45-term enum, folded from the 250 existing tags, dropping the non-descriptive ones (python,single-cell,bioinformatics,utilities, library names). Drives filtering and search.primary_category— the one category a package is listed under, for grouping.language— now mandatory to ensure that the schema is complete and doesn't break in random places.Both vocabularies mirror the tutorial registry, which already has
primary_categoryplus a controlledtagsenum, so the two registries share terminology. New terms get added to the enum in the PR that needs them.This breaks the open PRs by design: #391, #388, #385, #382, #378, #376, #375, #373, #372, #371, #368, #367, #364, #349, #348 and #327 need their
tagsmoved onto the vocabulary and aprimary_categoryadded.