glam/.opencode/rules/linkml/class-description-quality-rule.md

Class Description Quality Rule

Rule: Write Dictionary-Style Definitions Without Repeating the Class Name

When writing class descriptions, follow these principles.

1. No Repetition of Class Name Components

WRONG:

AcademicArchiveRecordSetType:
  description: >-
    A classification type for archival record sets created by academic
    institutions. This class represents the record set type...    

CORRECT:

AcademicArchiveRecordSetType:
  description: >-
    Category for grouping documentary materials accumulated by tertiary
    educational institutions during their administrative, academic, and
    operational activities.    

The description should define the concept using synonyms and related terms, not repeat words from the class name.

2. MIGRATE Structured Data Before Removing from Descriptions

CRITICAL: When a description contains structured data (examples, typical contents, alignment notes, etc.), you MUST:

1. First check if the structured data already exists in proper LinkML fields
2. If NOT present: ADD it to the appropriate structured field
3. ONLY THEN: Remove it from the description

Never simply delete structured content from descriptions without preserving it elsewhere.

MIGRATION CHECKLIST:

Content Type	Target Field	Example
Example instances	examples:	- value: {...} description: "..."
Typical contents	keywords: or comments:	List of typical materials
Alignment explanations	broad_mappings, related_mappings	Ontology references
Usage notes	comments:	Operational guidance
Provenance notes	comments: or annotations:	Historical context
Privacy/legal notes	comments:	Access restrictions
Definition details	Keep in description	Core semantic definition

WRONG - Deleting without migration:

# BEFORE (has rich content)
description: |
  Records documenting student academic careers.
  
  **Typical Contents**:
  - Enrollment records
  - Academic transcripts
  - Graduation records
  
  Subject to privacy regulations (FERPA, GDPR).  

# AFTER (lost information!) - DON'T DO THIS
description: >-
  Records documenting student academic careers.  

CORRECT - Migrate first, then clean:

# Step 1: Add to structured fields
description: >-
  Records documenting student academic careers.  
keywords:
  - enrollment records
  - academic transcripts
  - graduation records
comments:
  - Subject to privacy regulations (FERPA, GDPR, AVG)
  - Access restrictions typically apply for records less than 75 years old

# Step 2: Now description is clean but no information lost

3. No Structured Data or Meta-Discussion in Descriptions

After migration, descriptions should contain only the definition. Do not include:

• Alignment explanations (use broad_mappings, close_mappings, exact_mappings)
• Pattern explanations (use see_also, comments)
• Usage examples (use examples: annotation)
• Rationale for mappings (use comments: or annotations:)
• Typical contents lists (use keywords: or comments:)

WRONG:

description: >-
  A type for X. 
  
  **RiC-O Alignment**: Maps to rico:RecordSetType because...
  
  **Pattern**: This is part of a dual-class pattern with Y.
  
  **Examples**: Administrative fonds, student records...  

CORRECT:

description: >-
  Category for grouping documentary materials accumulated by tertiary
  educational institutions.  

broad_mappings:
  - rico:RecordSetType
see_also:
  - AcademicArchive
keywords:
  - administrative fonds
  - student records
examples:
  - value: {...}
    description: Administrative fonds containing governance records

4. Use Folded Block Scalar (>-) for Descriptions

Use >- (folded, strip) instead of | (literal) to ensure clean paragraph formatting in generated documentation.

WRONG:

description: |
  A type for X.
  This spans multiple lines.  

CORRECT:

description: >-
  A type for X. This will be formatted as a single clean paragraph
  in the generated documentation.  

5. Use LinkML examples: Annotation for Examples

Structure examples properly with value: and description: keys.

examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: University Administrative Records
  description: Administrative fonds containing governance records

6. Keywords vs Examples - Know the Difference

CRITICAL: Do not confuse keywords: with examples:. They serve different purposes:

Field	Purpose	Content Type
keywords:	Search terms, topics, categories	List of strings (topics/materials)
examples:	Valid instance data demonstrations	Structured objects with value and description

Keywords = Topics, material types, categories that describe what the class is about:

keywords:
  - enrollment records      # type of material
  - academic transcripts    # type of material
  - graduation records      # type of material

Examples = Actual instances of the class with populated slots:

examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Registrar Student Records
    has_note: Enrollment, transcripts, graduation records
  description: Student records series from the registrar's office

WRONG - Using keywords as examples:

# DON'T: "enrollment records" is not an instance of AcademicStudentRecordSeries
examples:
- value: enrollment records
  description: Type of student record

CORRECT - Keywords for topics, examples for instances:

keywords:
  - enrollment records
  - academic transcripts
  - graduation records
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Historical Student Records
    has_note: Pre-1950 student records with fewer access restrictions
  description: Historical student records open for research access

7. Multiple Examples for Different Use Cases

Provide multiple examples to show different contexts or configurations:

examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Recent Student Records
  description: Current records subject to privacy restrictions
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: Historical Student Records
  description: Records 75+ years old with fewer access restrictions

Summary

Element	Placement
Definition	description: (concise, no repetition)
Ontology mappings	exact_mappings, broad_mappings, etc.
Related concepts	see_also:
Usage notes	comments:
Metadata	annotations:
Examples	examples: with value and description
Typical contents	keywords: or comments: