Ontology Source References

This document records the shared helpers for parsing and creating ontology source references in Python and C#.

Canonical Formats

Document source references use the following forms:

doc://<document_id>
doc://<document_id>?p=<element_id>

Knowledge-graph source references use the following forms:

kg://<entity_id>
kg://<entity_id>/<source_label>.<source_attribute>

The optional KG qualifier identifies the source label and attribute that produced the reference. Consumers that only need to load the Neo4j entity must use the base <entity_id> and ignore the qualifier.

Python Helper

Location: PythonServer/src/services/ontology_source_helper.py

Key functions:

• build_doc_source_id() and build_kg_source_id() create canonical source tokens.
• parse_doc_source_token() parses document IDs and optional element IDs.
• parse_kg_source_token() accepts bare or qualified KG references, removes an optional query suffix and qualifier, and returns only the base entity ID.
• split_source_id_list(), join_source_id_list(), source_id_list_has_token(), and add_token_to_source_id_list() manage comma-separated source token fields using exact token matching.
• token_references_document() and remove_document_from_source_id_list() support document-reference cleanup and chapter/document normalization.

Python callers should use these helpers instead of manually splitting kg:// references.

C# Helper

Location: ThalabusWeb/Utilities/KnowledgeGraphSourceHelper.cs

KnowledgeGraphSourceHelper.Parse() accepts a KG source reference and returns (EntityId, AttributeName):

• EntityId is the base Neo4j entity ID.
• AttributeName is the final attribute name from a qualified source reference, or null for an unqualified reference.
• Both values are null for missing or non-KG input.

The Knowledge Graph source-details handler uses this helper to resolve a qualified source link to the entity side panel and focus the referenced attribute.