glam/.opencode/LINKML_TECHNICAL_CLASSES.md

LinkML Technical Classes: Exclusion from Visualizations

Date: 2025-11-28
Purpose: Document technical LinkML classes that should be excluded from semantic visualizations (UML, ERD, etc.)

---

Overview

Some LinkML classes exist solely for technical validation purposes and have no semantic/ontological significance. These classes should be excluded from UML diagrams, entity-relationship diagrams, and other visualizations that represent the domain model.

Metaphor: Like construction scaffolding - essential for building but not part of the final structure.

---

Excluded Classes

Container

Definition: schemas/20251121/linkml/modules/classes/Container.yaml

Container:
  description: >-
    Root container for validating complete instance documents.
    Contains top-level entity lists for each major class.
    Not used in RDF serialization (flattened).    
  tree_root: true
  attributes:
    # Lists of all entity types for validation
    custodian_observations: ...
    custodian_names: ...
    # ... etc.

Purpose:

• Enables linkml-validate -C Container instance.yaml validation
• Provides a tree_root entry point for parsing YAML/JSON instance documents
• Aggregates all entity types into a single validation target

Why Excluded:

• ❌ Has NO class_uri (not mapped to any ontology)
• ❌ Not serialized to RDF (explicitly stated in description)
• ❌ Purely structural - no domain semantics
• ❌ Would clutter diagrams with non-semantic relationships

Evidence:

# From Container.yaml - NO class_uri mapping
Container:
  tree_root: true
  # Notice: NO class_uri field - not mapped to any ontology

---

Exclusion Implementation

Python: Mermaid Diagram Generators

Files:

• scripts/generate_complete_mermaid_diagram.py
• scripts/generate_mermaid_modular.py

Pattern:

# Define excluded classes at module level
EXCLUDED_CLASSES = {"Container"}

# Filter in entity generation
for class_name, class_def in schema.classes.items():
    if class_name in EXCLUDED_CLASSES:
        continue  # Skip technical classes
    # ... generate entity definition

# Filter in relationship generation
for class_name, class_def in schema.classes.items():
    if class_name in EXCLUDED_CLASSES:
        continue
    for slot in class_def.attributes.values():
        if slot.range in EXCLUDED_CLASSES:
            continue  # Skip relationships to technical classes

TypeScript: Frontend UML Parsers

File: frontend/src/components/uml/UMLParser.ts

Pattern:

// Excluded technical classes (no semantic significance)
const EXCLUDED_CLASSES = new Set(['Container']);

// Filter function applied to all parsers
function filterExcludedClasses(entities: UMLEntity[]): UMLEntity[] {
  return entities.filter(entity => !EXCLUDED_CLASSES.has(entity.name));
}

// Applied in each parser
export const parseMermaidClassDiagram = (content: string): UMLDiagram => {
  // ... parse entities
  const filteredEntities = filterExcludedClasses(entities);
  // ... return filtered diagram
};

---

How to Add New Exclusions

When you identify a new technical class that should be excluded:

Step 1: Verify It's Truly Technical

Check these criteria:

• Has no class_uri (not mapped to any ontology)
• Documentation states it's not for RDF serialization
• Exists only for validation/parsing purposes
• Has no domain semantics

Step 2: Add to Python Generators

In both generator scripts, add to the EXCLUDED_CLASSES set:

# scripts/generate_complete_mermaid_diagram.py
# scripts/generate_mermaid_modular.py

EXCLUDED_CLASSES = {"Container", "NewTechnicalClass"}

Step 3: Add to Frontend Parser

In frontend/src/components/uml/UMLParser.ts:

const EXCLUDED_CLASSES = new Set(['Container', 'NewTechnicalClass']);

Step 4: Document in This File

Add a new section under "Excluded Classes" with:

• Definition location
• Purpose description
• Reason for exclusion
• Evidence (no class_uri, etc.)

Step 5: Regenerate Diagrams

cd /Users/kempersc/apps/glam
python scripts/generate_complete_mermaid_diagram.py
python scripts/generate_mermaid_modular.py
# Verify class count decreased

---

Verification

Check Current Diagram Class Count

# Count classes in latest diagram (should NOT include Container)
grep -c "class " schemas/20251121/uml/mermaid/complete_schema_*.mmd | tail -1

# Verify Container is NOT in diagram
grep "Container" schemas/20251121/uml/mermaid/complete_schema_*.mmd
# Should return no matches

Expected Results (as of 2025-11-28)

• Total classes in schema: 72 (including Container)
• Classes in diagrams: 71 (Container excluded)
• Frontend visualization: 71 classes (Container filtered)

---

Why This Matters

For AI Agents

When generating or analyzing UML diagrams:

• ✅ DO: Focus on the 71 semantic classes
• ❌ DON'T: Expect to see Container in diagrams
• ❌ DON'T: Add Container to ontology mappings

For Developers

When modifying diagram generators:

• ✅ DO: Apply exclusion filters consistently
• ❌ DON'T: Hardcode class names in multiple places (use the constant)
• ✅ DO: Document new exclusions in this file

For Schema Designers

When adding new technical classes:

• ✅ DO: Mark them with tree_root: true if for validation
• ✅ DO: Omit class_uri if not semantically meaningful
• ✅ DO: Add to exclusion lists in generators
• ✅ DO: Document purpose in class description

---

Related Documentation

• AGENTS.md: Rule 0 - LinkML Schemas Are Single Source of Truth
• .opencode/SCHEMA_GENERATION_RULES.md: Generation workflow
• .opencode/HYPER_MODULAR_STRUCTURE.md: Module organization
• schemas/20251121/linkml/modules/classes/Container.yaml: Container definition

---

Status: ✅ ACTIVE
Version: 1.0
Last Updated: 2025-11-28
Applies To: All UML/ERD diagram generation in this project