Model Comparison & Release Notes

Compare your current model against another model to see what has been added, modified, or removed. Model Comparison helps you track evolutionary changes, review AI-generated modifications, merge version updates with granular control, and generate professional release notes and changelogs.

Accessing Model Comparison

You can access Model Comparison from multiple places in Termboard:

1. Top Menu: File > Compare with... or Tools > Compare Models to open the Compare Models workspace in the right sidebar.
2. Right Tools Sidebar: Select Compare Models directly from the tool selector dropdown in the right sidebar.
3. Document Pickers: Click the compare action button next to any saved document in the document list.
4. Document Properties: Click Compare with Parent directly inside File > Document Properties.

Selecting a Model to Compare

Termboard offers convenient ways to select a model to compare against your active canvas:

1. Lineage Quick-Select (Ancestors, Siblings & Branches)

If your current model was created from a parent or has derived copies, they appear immediately in the comparison sidebar:

• Parent Documents: Lists immediate parents and surviving ancestors.
• Sibling Documents: Lists parallel branches derived from the same parent model.
• Child Documents: Lists direct children and evolutionary branches.
• Click any listed parent, sibling, or child to start comparing instantly without searching.

2. Browser Storage

Click Browser Storage to open the full Document Picker modal in compare mode. You can search, browse folders, and view version tags. Clicking any document loads it into the comparison slot without modifying or clearing your canvas.

3. JSON File

Click JSON File to open the file selection dialog. Drag and drop any Termboard .json model file (or click to browse your file system) to compare against your active canvas.

Comparison Concepts & Terminology

To keep comparison clear and intuitive, Termboard uses consistent terminology across the sidebar and dialogs:

Term	Snapshot & Delta Indicator	Vocabulary Alignment Indicator	Meaning
Current Canvas	CANVAS:	CANVAS:	Your active canvas currently open and editable in Termboard.
Compared Model	COMPARED:	COMPARED:	The baseline, patch, or standard model loaded from browser storage or a JSON file.
Added	+ Add	+ Gaps	Element exists only in the compared model. In Snapshot/Delta, applying adds it to canvas; in Alignment, it represents unadopted standard concepts.
Modified	Δ Mod	Δ Divergent	Element exists in both models but has field differences (descriptions, types, custom attributes).
Removed	- Rem	- Proprietary	Element exists only on your current canvas. In Snapshot, applying deletes it; in Delta, out-of-scope items are preserved; in Alignment, items are proprietary concepts kept intact.
Unchanged	= Same	= Shared	Element is identical in both models with matching field values.
Out of Scope	Untouched	Proprietary	(Delta mode) Canvas elements outside the scope of a modular patch. Preserved automatically and protected from deletion.

---

Multi-Paradigm Comparison Modes

Model comparison serves fundamentally different purposes depending on whether you are upgrading a release, applying an incremental patch, or benchmarking against an industry standard. Termboard provides three dedicated comparison modes:

Mode	Paradigm	Matching Strategy	Deletion Handling	Primary Use Case
Snapshot	Full Sync	Hybrid (ID + Name)	Strict Full Sync	Upgrading model to next release, merging parallel branches, or restoring backups.
Delta Patch	Scoped Modular Patch	Hybrid (ID + Name)	Scoped Deletions Only	Merging partial domain contributions, Excel table slices, or AI brainstorming additions.
Vocabulary Alignment	External Benchmark	Concept Name + Synonyms + Fuzzy	Non-Destructive (Deletions Disabled)	Comparing against industry standards (FIBO, FHIR, BMM), adopting standard definitions, and calculating vocabulary coverage.

Mode Selection

You can switch modes at any time in the Filter Options menu () by clicking Snapshot, Delta, or Align (see Search & Filters). Termboard can also auto-detect partial patches or standard ontologies and prompt you to switch mode with a single click.

1. Snapshot Mode (Default)

Active when Snapshot is chosen in the Search & Filters menu. In Snapshot mode, the compared model represents the complete desired future state of your canvas. Any concept currently on your canvas that is absent from the compared model is treated as Removed and scheduled for deletion if deletions are applied.

• Best for: Whole-model migrations, version milestones (v1.0 → v2.0), restoring clean backups.
• Actions: Full synchronization (Update & Add, Update Only, Add Only, Delete Only / Apply All Inc. Deletes).

2. Delta Patch Mode

Active when Delta is chosen in the Search & Filters menu, or when accepting the auto-detection suggestion banner. When collaborating across teams or incorporating AI expansions, contributors often export only the specific concepts they worked on. In Snapshot mode, importing a 10-concept patch against a 400-concept canvas would falsely mark 390 concepts as deleted.

Delta Patch Mode solves this with scoped patch semantics:

• Preserved Out-of-Scope Canvas Items: Root canvas concepts omitted from the patch are tagged as outOfScope and shown under Out of Scope (Untouched). They are excluded from deletion actions. (Note: If a canvas term's parent container is modified or part of the patch, it is treated as an in-scope deletion).
• Scoped Relation Deletions: A relation on your canvas is only considered for removal if both of its endpoint terms were included in the patch (or are in-scope deleted terms). If either endpoint is outside the patch, the relation is preserved.
• Cross-Boundary Relation Stitching: Incoming relations in the patch that connect to existing canvas terms are automatically linked without creating duplicate terms or broken links.
• Delete Guard: Even if you trigger "Apply All" or run a deletion action, Termboard's reconciliation engine guarantees that out-of-scope canvas concepts are protected.
• Smart Auto-Detection Banner: When you load a model that represents an incremental addition or slice, Termboard displays an interactive suggestion banner:

  "Partial patch detected (matches canvas, omits N terms). Treat as Delta Patch?"
  [Switch to Delta] [×]

3. Vocabulary Alignment Mode (External Benchmarks)

Active when Align is chosen in the Search & Filters menu. When comparing your proprietary domain model against an external reference ontology (e.g. FIBO for finance, FHIR for healthcare, Schema.org for web metadata), neither model is intended to replace the other. Instead, the goal is gap analysis, vocabulary overlap calculation, and definition adoption.

Vocabulary Alignment Mode provides dedicated benchmark tools:

• Concept-Oriented Matching: Bypasses internal UUID matching. Concepts are matched by canonical name and synonyms regardless of origin or database ID.
• 1:1 Synonym Matching: Evaluates concept synonym lists. When a canvas concept's name or synonym unambiguously matches a standard concept, it is identified as a candidate match.
• Automatic Fuzzy Matching: Name similarity matching (≥85% threshold) is active by default to surface morphological variants.
• Real-Time Venn Overlap Metrics: A summary breakdown displays:
  • Overlap %: Jaccard similarity score between canvas and benchmark vocabularies.
  • Shared Vocabulary: Concepts present in both models.
  • Standard Gaps: Concepts in the standard not yet adopted in your canvas.
  • Divergent Definitions: Concepts shared by name or synonym that differ in definitions or attributes.
  • Proprietary Concepts: Canvas-exclusive concepts preserved without deletion.
• One-Click Adoption Actions:
  • Adopt All (Gaps & Updates): Merges all unadopted concepts and updates divergent definitions.
  • Adopt Updated Definitions (${count}): Updates your local canvas definitions with authoritative standard descriptions and attributes.
  • Adopt Missing Concepts (${count}): Brings selected standard concepts onto your canvas to fill coverage gaps.
  • Deletions are completely disabled to ensure safe, non-destructive alignment.
• Vocabulary Alignment & Coverage Report: The report generator provides a publication-ready Coverage Report detailing overlap percentages, gap inventories, and definition differences.

---

The Tools Sidebar Widget

The Compare Models tool provides an inline comparison workspace alongside your active canvas:

• Target Selector: Select from browser-stored documents or upload a local JSON file.
• Model Info & Swap: Displays Current Canvas (CANVAS:) and Compared Model (COMPARED:) with a mode badge and swap icon to change the compared model.
• Auto-Detection Suggestion Banner: Intelligently identifies when an imported file is a partial patch (suggesting Delta Mode) or an external benchmark (suggesting Alignment Mode) with one-click switching.
• Probable Renames Banner: Detects potential renamed concepts based on name similarity (≥75%), with inline Accept, Dismiss, or batch actions.
• Venn Summary Card (Alignment Mode): Displays real-time vocabulary overlap percentage, shared concept counts, standard gaps, divergent definitions, and proprietary terms.

Search & Filters

• Search: Filter changes by name in real time.
• Filter Options ():
  
  
  • Comparison Mode: Switch between modes (see Multi-Paradigm Comparison Modes for complete semantics and rules):
    • Snapshot: Full closed-world sync (V1 → V2). Missing canvas concepts marked for deletion. (See Snapshot Mode).
    • Delta: Open-world modular patch. Out-of-scope canvas items preserved and protected by Delete Guard. (See Delta Patch Mode).
    • Align: External standard benchmark. Concept name and synonym matching with Venn metrics and definition adoption. (See Vocabulary Alignment Mode).
  • Change Type: Filter by status (All, Δ Mod, + Add, - Rem, = Same, or mode-adapted labels in Alignment mode, plus Untouched / Proprietary for out-of-scope elements).
  • Element Type: Toggle visibility between Both, Terms, or Relations.
  • Structure: Filter by structural impact: All, 📦 Containers (parent-child grouping changes), or 🏷 Hierarchy (taxonomy relationships).
  • Fuzzy Matching: Toggle name similarity matching (≥85% threshold; always active in Alignment mode).
  • Active Indicator: A dot badge indicates active filters, with a Reset Filters button to restore defaults.

Actions Toolbar & Controls

• Actions Menu (Actions (count) or Adopt (count)):
  • Apply to Canvas (Snapshot & Delta Modes):
    • Update & Add: Updates modified items with selected fields and adds new items.
    • Update Only: Applies updates to existing matched items, ignoring new elements.
    • Add Only: Adds newly introduced items from the compared model.
    • Delete Only / Apply All (Inc. Deletes): Safely handles deletions with cascade warnings when deletions are staged. In Delta mode, canvas items outside the patch scope are protected by Delete Guard.
  • Adopt Actions (Alignment Mode):
    • Adopt All (Gaps & Updates): Merges all unadopted concepts and applies divergent definitions.
    • Adopt Updated Definitions (${count}): Updates local canvas definitions with authoritative standard descriptions.
    • Adopt Missing Concepts (${count}): Adds unadopted benchmark concepts to your canvas.
  • Reports:
    • Change Report (Snapshot/Delta) / Coverage Report (Alignment): Launches the report dialog (see Automated Release Notes Generator).
• Canvas Refresh (): Highlights when canvas changes occur and prompts you to recalculate diffs.
• Inspection & Preview: Click any item to center it on the canvas, or click the eye icon () to open the Diff Viewer.

---

Detailed Diff & Preview Viewer

Click the eye icon () on any row in the changes list to open the modal Diff Viewer dialog. Preview is supported across all change types:

1. Modified Concepts & Relations (Modified)

For elements that exist in both models with field changes:

• Side-by-Side View: Compares Current Canvas on the left and Compared Model on the right in synchronized columns.
• Inline View: Displays differences in a unified list with color-coded strike-through and additions.
• Granular Cherry-Picking: Check or uncheck individual fields (name, description, type, parent, xFields) to select exactly which changes to adopt.
• Apply to Canvas: Click Apply X Fields to Canvas to merge only the selected fields immediately.

2. Added Concepts & Relations (Added)

For elements that exist only in the compared model:

• Rich Preview: Inspect incoming properties before importing, including concept type, parent/container, full description, additional notes, synonyms, URL, weight, custom xFields, and relation endpoints.
• Single-Click Import: Click Add to Canvas to add just this single element to your current canvas without applying all changes in batch.

3. Removed Concepts & Relations (Removed)

For elements that exist on your current canvas but are absent from the compared model:

• Pre-Deletion Audit: Inspect the element's existing definition, parent, and attributes before making a destructive decision.
• Single-Click Delete: Click Delete from Canvas to remove only this element (with automated cascade protection warning you if connected relations exist).

4. Unchanged Elements (Unchanged)

For elements identical in both models:

• Reference Inspection: Inspect all attributes and metadata in read-only mode for baseline verification.

---

Selective Reconciliation & Merging

Termboard gives you fine-grained control when merging changes from the compared model into your active canvas.

1. Select Items to Reconcile

Use checkboxes in the changes table to select individual items, or use the header checkbox to select all filtered items.

Automatic Relation Dependency Resolution

When you select a relation for import from the compared model, Termboard automatically detects if its source or target terms are missing from your current canvas. It automatically includes those required terms so that relations are never broken or orphaned.

2. Configure Field-Level Updates

For individual elements marked as Modified, you can cherry-pick specific fields:

1. Click the eye icon () on any modified item to open the Diff Viewer.
2. Select which fields should be adopted (e.g. adopt updated descriptions while preserving local concept types).
3. Click Apply Selected Fields to Canvas to merge them immediately into your active canvas.

3. Choose Reconciliation Strategy

Click the Actions (or Adopt) menu and choose the appropriate strategy:

• Update & Add: Updates modified items with selected fields and adds new items from the compared model into your active canvas.
• Update Only: Applies updates to existing matched items, ignoring new items.
• Add Only: Adds newly introduced items from the compared model, leaving existing matched items untouched.

Single-Step Undo Safety

All reconciliation operations are applied as a single atomic transaction. If you want to revert the merge, simply press Ctrl+Z (or use the Undo button in the canvas toolbar) to restore your previous model state completely.

---

Automated Release Notes Generator

Model Comparison includes a built-in Release Notes Generator that transforms structural and content differences into clear, professional documentation for stakeholders, clients, and technical teams.

How to Generate Release Notes

1. In the Compare Models sidebar tool, click the Actions menu and select Change Report (or Coverage Report in Alignment mode).
2. The Report dialog opens automatically, analyzing all differences between your current canvas and the compared model.
3. Use the Annotate tab to review, curate, and enhance your release notes:
   • Edit the Executive Summary directly or generate/regenerate it with AI ().
   • Add an Author Narrative to contextualize business drivers.
   • Tag breaking changes, add rationale notes, and supply migration steps per changed concept or relationship.
4. Preview the formatted document in the Document Preview tab or view the raw source in the Markdown tab.

Release Notes Structure

The generator structures the report into clear, business-friendly sections:

• Header & Metadata: Document title, baseline model, comparison target, and generation timestamp.
• Executive Summary: High-level metrics summarizing added concepts, modified terms, removed items, and relationship changes, enhanced with domain rationale.
• Author Narrative: Commentary and introduction written for stakeholders.
• ✨ Added Concepts: Detailed list of newly introduced terms, including their assigned types and descriptions.
• ✏️ Modified Concepts: Clear breakdown of changed terms, detailing exact modifications per field (e.g., updated definitions, changed classifications).
• 🗑️ Removed Concepts: List of deprecated or removed terms.
• 🔗 Relationship Updates: Changes in semantic links, hierarchy links, and associations between concepts.
• 🛡️ Semantic Integrity Scorecard: Reports resolved descriptions, newly un-described concepts, multi-parent hierarchy risks, and potential cycle warnings.

Vocabulary Alignment & Coverage Report (Alignment Mode)

When comparing models in Vocabulary Alignment mode, release notes are automatically tailored as a Vocabulary Alignment & Coverage Report:

• Executive Summary & Venn Metrics: Highlights the overall vocabulary overlap percentage, count of shared concepts, count of standard gaps (unadopted external concepts), and divergent definitions.
• Coverage Breakdown:
  • Shared Concepts: Concepts aligned between your model and the standard.
  • Standard Gaps (Unadopted): Concepts in the benchmark ontology missing from your model.
  • Divergent Definitions: Concepts shared by name or synonym whose definitions, classifications, or properties diverge from the standard.
  • Proprietary Concepts: Concepts unique to your canvas, preserved as proprietary intellectual property.
• Export Options: Export as Markdown (.md), standalone responsive HTML (.html), or Excel (.xlsx) with dedicated alignment columns and coverage sheets.

Export Formats & Sharing

The toolbar in the report dialog provides one-click export options:

• Download Markdown (.md): Save directly as a GitHub-Flavored Markdown file ready for GitHub/GitLab releases, Jira, Obsidian, or project wikis.
• Download HTML (.html): Styled, self-contained HTML ready for publishing on internal intranets, emailing to stakeholders, or embedding in reports.
• Download Excel (.xlsx): Comprehensive workbook including Summary, Terms, and Relations sheets with user annotations.
• Print / PDF: Browser-native print formatting optimized for PDF export and distribution.
• Copy Markdown: One-click clipboard copy.

---

Excel Export

For compliance documentation, auditing, or spreadsheet analysis, you can export comparison results to Excel directly from the Change Report toolbar (Download Excel):

The exported workbook includes:

• A Summary sheet providing overall statistics, comparison parameters, and Venn overlap percentages in Alignment mode.
• A Terms sheet detailing all term diffs, categories, statuses, and custom annotations (Rationale, Migration Guide, Breaking, Tag).
• A Relations sheet detailing all relation diffs, endpoint flows, and annotations.

---

Matching Strategy

Termboard uses an intelligent multi-strategy matching engine adapted to your selected comparison mode:

1. Snapshot & Delta Modes (ID-First Hybrid)

1. ID Match: Elements are first matched by their unique identifier (id). This ensures exact tracking even when an item has been heavily renamed.
2. Name Match: If an ID match is not found, elements are matched by concept name (case-insensitive and trimmed).
3. Synonym Match: Evaluates 1:1 unambiguous synonyms to align concepts.
4. Probable Renames: Detects candidate renames among unmatched items based on name similarity (≥75%).
5. Fuzzy Matching: Optional name similarity matching (≥85% threshold) can be toggled in the filter menu.

2. Vocabulary Alignment Mode (Concept-First Semantic)

Because external ontologies and benchmark standards use different naming and ID schemes:

1. Name Match: Matches concepts directly by canonical name, skipping arbitrary internal IDs.
2. Synonym Expansion: Checks the synonym lists of both models for unambiguous 1:1 candidate matches.
3. Automatic Fuzzy Matching: Name similarity matching (≥85% threshold) is active by default to bridge minor spelling variations and hyphenations.

---

Practical Use Cases

1. Reviewing AI-Generated Modifications

Before applying extensive automated changes with an AI assistant or prompt workflow:

1. Save a snapshot of your model to browser storage.
2. Run your AI generation or bulk enrichment.
3. Open Compare Models against your saved snapshot to review every suggested addition or modification before committing to them.

2. Release Management & Version Control

When publishing a new model version (e.g., transitioning from v1.0 to v1.1):

1. Compare your working draft against the last published release.
2. Verify all intended modifications and check for unintentional deletions.
3. Open Actions > Change Report to produce instant release documentation for project stakeholders.

3. Merging Branch Models or Collaborative Work

When collaborating asynchronously:

1. Compare your colleague's exported JSON file against your active canvas.
2. Review new terms and relationships.
3. Selectively merge only the approved concepts using Update & Add with dependency resolution.