BDCHM Interactive Documentation

BioData Catalyst Harmonized Model — Schema Explorer

Target release: July 30, 2026

This page documents the current state of the interactive schema explorer, what's been built, what remains, and open design questions. The app itself is at sigfried.github.io/dynamic-model-var-docs.

⚠️ This page predates the June 11, 2026 feedback round and needs updating. The current plan reframes the audience around researchers (data users and study designers pre-harmonizing with BDCHM), not only modelers, and reprioritizes the work: (1) configurable plain-language vs. LinkML terminology, (2) a more compact Kitchen Sink with progressive disclosure and multi-class selection, (3) a node-link/tree visualization for a user-selected subset of entities, and (4) contextual help mode. The containment-graph work shown below is now parked. Open questions for the team (whether to merge the two views, which audience to optimize defaults for) are deliberately left undecided. See the up-to-date plan in temp-but-share-for-now/STAKEHOLDER_QUESTIONS.md and the retriaged backlog in docs/TASKS.md.

What's Shipped

Entity Explorer (default view)

Progressive-disclosure interface replacing the original multi-panel layout. Entities organized by category (Admin/Study, Clinical, Observations/Measurements, Lab/Biospecimen, Survey, Files/Other) with a Pinned section at top. Click an entity to drill down into its properties and variables. Click a range badge to see enum details (permissible values, usages) or to recursively drill into another entity. Subclass indentation for inheritance relationships. Pin/unpin entities to customize the top section. The old "Kitchen Sink" multi-panel view is still available via a toggle in the header.

live progressive disclosure recursive drilldown pinning

Kitchen Sink view (legacy)

The original multi-panel layout with link overlays connecting classes to their ranges, detail popups, relationship info boxes, and variable tables. All entity types (classes, enums, slots, types, variables) visible simultaneously. Still accessible via the Explorer/Kitchen Sink toggle in the header.

legacy view links + panels

Explorations & Mockups

Standalone proof-of-concept visualizations exploring model structure. Not yet integrated into the main app.

Containment Tree

Interactive indented list showing the full containment hierarchy rooted at ResearchStudyCollection. BDCHM uses FK-style back-references (child points to parent), so single-valued entity references are inverted to show "what contains what." Inheritance subclasses nested inline with diamond markers, showing only their own additional slots. Expand/collapse, hide-subclasses toggle, dark mode.

exploration containment FK inversion

Containment Graph

Cytoscape + dagre node-link diagram of the containment hierarchy (49 nodes, 95 edges). Three edge types: solid (has-a), purple (flipped FK), dashed green (is-a subclass). Click nodes to highlight neighborhoods. Multiple layouts (top-down, left-right, force-directed). Legibility is borderline at full scale — motivates the "pin a subset" approach below.

exploration graph Cytoscape + dagre

What's Next

in progress Pinned-entity diagram. Let users select a set of entities and generate a focused containment diagram with just those entities and their relationships. Uses the FK-inversion heuristic from the containment tree. Graph renderer TBD (Cytoscape/dagre, ELK, or adapted from the icd11-playground's D3+ELK renderer).
in progress Non-LinkML terminology. The Entity Explorer now labels slots as Properties. Still to do: general-audience terms for the rest (value set for enum, property type for range), LinkML equivalents shown in tooltips, and possibly a toggle between "general" and "LinkML" vocabulary modes.
todo Search / filter. Search across entity names, descriptions, slot names, and variable labels. Auto-expand categories with matches.
todo URL state encoding. Persist expanded entity, drilldown tab, and open inline cards to the URL for deep-linking and browser back button support.
todo Enum detail: CURIE labels and definitions. Show CURIE labels and definitions in enum detail cards, not just the CURIE identifiers.
todo Render markdown in schema fields. Some descriptions (e.g., UnitOfMeasurementEnum) contain markdown but are currently rendered as plain text.

Open Design Questions

Model structure: is-a vs has-a

BDCHM follows relational FK conventions — references point from child to parent. For a containment view, we invert single-valued entity references. A small override list handles exceptions. The heuristic needs validation with the model designer.
ResearchStudyCollection is the top-level container, but the has-a hierarchy doesn't form a clean tree (some entities are referenced by multiple parents, some are associational references rather than containment).
The full-model graph (49 nodes, 95 edges) is borderline legible. A "pin a subset and generate a focused diagram" approach may be more useful than trying to show everything.

User audience

Balancing: NHLBI (customer), data quality presentation, end-user experience, and internal dogfooding (team's own use of the tool).
Non-technical users want simpler terms; technical users want LinkML precision. Progressive disclosure can serve both: general terms by default, LinkML terms in tooltips or via a toggle.

Where do links fit?

The old Kitchen Sink view's curving-line connections were visually appealing and gave an immediate sense of structure. Some stakeholders want to keep them available.
The Entity Explorer's inline drilldown and "referenced by" lists provide the same relationship information in a more compact, contextual way.
Possible compromise: links as an optional overlay or a separate "Relationships" tab/view, rather than the default.

Variable Library dependency

Once the Variable Library is live, variable drilldowns in the Entity Explorer can be simplified or removed — variables will have their own dedicated tool.