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`

```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**:
```yaml
# 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**:
```python
# 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**:
```typescript
// 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:

```python
# 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`:

```typescript
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

```bash
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

```bash
# 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