Topics¶

Each namespace keeps a controlled vocabulary of topics: what its assets are about. Topics are separate from entities. Entities are the named things an asset's text mentions (people, organisations, products, places); a topic is a subject someone chose for the vocabulary, like "Gene therapy" or "Funding".

Status: built: the vocabulary (labels, definitions, broader, narrower and related topics), assets about topics, topics made from topic-like entities, the API, the Topics page, an asset's topics, topics in the graph (and on its canvas) and in RDF, topic suggestions from analysis, # links in notes, a page per topic, and assistant and MCP tools for topics.

In the web app¶

Topics in the navigation shows a namespace's vocabulary as a tree: top topics first, each opening onto its narrower ones (a topic under two broader topics shows under both). Search finds topics by any of their labels. Pick a topic to edit it in a drawer: its labels, definition, broader and related topics, its narrower topics, and the assets about it, where suggested ones can be accepted or removed. Merge in the drawer opens a find box: type part of a label and pick (or press Enter) to merge that topic into this one at once. Delete deletes it at once. Both say what they did with Undo on the message, so there is no confirm step. Editors add topics at the top or under another with +. A graph workflow can also group a flat vocabulary under broader topics on a routine, proposing or making the groups it finds (Organising the graph).

An asset's Entities tab starts with its topics: editors add one from the vocabulary, take one off, or accept or dismiss a suggestion. An entity of type Term has Make a topic in its drawer. On the graph canvas topics are green tags, with About, Narrower and Related edges; ask the graph (for example MATCH (t:Topic) RETURN t) or open an asset's children to bring them in. Editors edit a topic from the graph (Edit… on a node's menu, or Edit in its panel) and merge one into another with Merge into another… and a click on the one to keep.

A topic¶

A topic follows SKOS, the W3C standard for vocabularies:

Field	SKOS	What it is
label	`skos:prefLabel`	Its name. Unique in the namespace.
alt	`skos:altLabel`	Other labels it goes by (synonyms, abbreviations, spellings). Unique in the namespace too.
definition	`skos:definition`	What it covers, in your words.
broader	`skos:broader`	The wider topics it belongs under. A topic can have several; it can't end up under itself.
narrower	`skos:narrower`	The topics that have it as broader (kept from their side).
related	`skos:related`	Topics that are related but not broader or narrower. Kept on both sides.

Assets are about topics. A person says so, a topic made from an entity brings the assets that mention it, and analysis suggests topics for someone to accept. Each link records where it came from (person, entity, analysis) and whether it holds (accepted), waits (suggested) or was turned down (dismissed).

Suggestions from analysis¶

Analysis never changes the vocabulary or what an asset is about on its own; it suggests, and people decide. No language model is called for it: it reuses what analysis already found.

Topics for assets. An asset gets a topic as a suggestion when its summary names one of the topic's labels, or its text mentions one of them (a label of one or two words) at least twice. Labels match whatever their case or plural. This runs after each analysis and summary, and over the whole namespace when a topic is added, renamed, given other labels or merged. Accepting keeps where it came from; dismissing is remembered, so analysis doesn't suggest that topic for that asset again. Suggestions that no longer match go.
New topics. The Topics page lists, under Suggested by summaries, what summaries say assets are about that no topic covers yet, with how many assets say it (GET /api/v1/namespaces/{name}/topics/candidates). Adding one creates the topic, and its assets get it as a suggestion. Skipping one (POST /api/v1/namespaces/{name}/topics/candidates/skip) stops it being offered. A namespace's vocabulary is fixed until someone adds to it.

Topics and entities¶

Until now a topic was an entity of type TERM, which is also the type analysis gives anything it can't classify. Turn such an entity into a topic (POST /api/v1/entities/{id}/topic): its name becomes the label, its aliases the other labels, its description the definition, and the assets that mention it are about the topic. The entity is hidden while the topic exists; deleting the topic shows it again. If the namespace already has a topic of that name, the assets join it.

Deleting a topic moves its narrower topics up to its broader ones. Merging topics makes the others' labels the kept topic's other labels and brings their assets over.

Either can be undone: the topics come back with their ids, labels, definitions, recordings and note pages, the broader and related lists they were taken out of are put back, and a topic made from an entity hides that entity again. Whatever changed since stays. Undo is refused when another topic has taken one of their labels meanwhile: rename that one first.

Rights¶

Reading needs a role in the namespace; changing the vocabulary or which assets are about a topic needs the editor role there. Every change is in the audit log (topic.create, topic.update, topic.delete, topic.merge, topic.tag, topic.untag, topic.from_entity, topic.merge.undo, topic.delete.undo).

The API¶

Call	What it does
`GET /api/v1/topics?ns=&q=&top=&broader=`	Topics by label, with how many assets are about each and how many narrower topics it has.
`GET /api/v1/topics/{id}`	A topic with its broader, narrower and related topics and the assets about it.
`POST /api/v1/namespaces/{name}/topics`	Add a topic `{label, alt, definition, broader, related}`.
`PATCH /api/v1/topics/{id}`	Change any of those; an empty definition clears it.
`DELETE /api/v1/topics/{id}`	Delete it; the answer's `undo` takes it back.
`POST /api/v1/topics/merge` `{keep, others}`	Merge topics into one; the answer's `undo` takes it back.
`GET /api/v1/namespaces/{name}/topics/changes`	The latest merges and deletes, newest first, each with whether it was undone.
`POST /api/v1/topics/changes/{id}/undo`	Take a merge or a delete back.
`POST /api/v1/topics/{id}/recordings` `{recordings, remove}`	Say assets are about it, or aren't.
`GET /api/v1/resources/{id}/topics`	The topics an asset is about, and those suggested.
`POST /api/v1/entities/{id}/topic`	Make a TERM entity a topic.

In the graph and in RDF¶

In the property graph (The graph) a topic is a Topic node t<id>, and assets link to it with ABOUT; broader topics link to narrower ones with NARROWER, and related ones with RELATED. ABOUT and NARROWER are part of the hierarchy, so a topic's ancestors are its broader topics and the assets about it. TERM entities are labelled Term there, so they aren't confused with topics.

// assets about gene therapy or anything narrower
MATCH (t:Topic)-[:NARROWER*0..6]->(n:Topic)<-[:ABOUT]-(r:Recording)
WHERE toLower(t.name) = 'gene therapy'
RETURN DISTINCT r.name, n.name

In RDF (Linked data) a topic is /id/topic/<id>, a skos:Concept in the namespace's vocabulary /id/namespace/<name>#topics (a skos:ConceptScheme), and assets name the topics they are about as dcterms:subject.

Refine later¶

Vocabularies shared by several namespaces, and imported schemes (LCSH, Wikidata) linked with skos:exactMatch.
Entities as authority records: variant names and external identifiers.
A page listing the latest topic merges and deletes, to undo one after its message has gone.
Picking several topics on the Topics page to merge them in one go.

Notes, the assistant and agents¶

In notes, # links a topic (#[Capsid design](topic:9)), found by any of its labels, and every topic has a page of its own (Page in its drawer) that lists the notes linking to it. Deleting or merging a topic keeps its page, as a free note.

The assistant in Chat finds topics (find_topics), reads one with its assets (topic_recordings) and, for editors, suggests a topic for assets (suggest_topic). The MCP server has the same as list_topics, get_topic and suggest_topic (with a write-scope token). Suggestions from either wait for someone to accept them, with assistant as their source; what people accepted or dismissed stays as it is.

Asked to tidy the vocabulary, the assistant proposes merging, renaming, describing or deleting a topic (propose_topic_change), which happens only when the person approves it, in Chat or with a yes in a chat room. With a write-scope token, agents edit, merge and delete topics over MCP (edit_topic, merge_topics, delete_topic) and take a merge or delete back with undo_topic_change.