---
Goal
Improve the quality of LinkML class files in a GLAM (Galleries, Libraries, Archives, Museums) ontology project by:
1. Writing proper dictionary-style descriptions without repeating class names
2. Adding multilingual support (alt_descriptions and structured_aliases in 7 languages: nl, de, fr, es, ar, id, zh)
3. Structuring data properly using LinkML annotations (examples:, keywords:, comments:)
4. Ensuring all ontology mappings use the correct category (exact_mappings vs broad_mappings vs close_mappings vs narrow_mappings vs related_mappings)
5. Verifying all Wikidata mappings are semantically correct
6. Creating and updating rules in .opencode/rules/
Instructions
Key Rules Created/Updated
1. class-description-quality-rule.md: 
   - No repetition of class name in descriptions
   - MIGRATE structured data before removing from descriptions
   - Use folded block scalar (>-)
   - Use examples: annotation properly
2. linkml-yaml-best-practices-rule.md:
   - equals_expression anti-pattern → use equals_string or any_of
   - Declare all prefixes
   - Import referenced classes
   - Quote regex patterns and annotation values
3. class-multilingual-support-rule.md:
   - Required languages: nl, de, fr, es, ar, id, zh
   - Structure for alt_descriptions and structured_aliases
4. mapping-specificity-hypernym-rule.md (updated):
   - Classes that are NEVER exact mappings: schema:Action, schema:Organization, schema:Thing, schema:PropertyValue, schema:Permit, prov:Activity, skos:Concept, crm:E55_Type, crm:E42_Identifier, dcat:DataService
   - Type compatibility: class→class, property→property
   - Decision tree for mapping type
5. wikidata-mapping-verification-rule.md:
   - Use wikidata-authenticated_execute_sparql to verify QIDs
   - SPARQL templates for batch verification
6. wikidata-mapping-discovery-rule.md (updated):
   - ALWAYS verify BOTH label AND description before adding
   - Check type compatibility (organization→organization, NOT organization→building)
   - Examples of WRONG mappings found: Q22075301 (textile artwork) was mapped to FacultyPaperCollection!
   - "Better no mapping than wrong mapping" principle
Discoveries
1. Wrong Wikidata mappings found and removed:
   - Q22075301 (textile artwork) → was mapped to FacultyPaperCollection ❌
   - Q1643722 (building in Vienna) → was mapped to UniversityAdministrativeFonds ❌
   - Q185583 (candy) → was mapped to AcademicStudentRecordSeries ❌
2. Wrong mapping categories corrected:
   - schema:Action was exact_mappings → should be broad_mappings
   - crm:E55_Type was exact_mappings → should be broad_mappings
   - prov:Activity was exact_mappings → should be broad_mappings
   - schema:Organization was exact_mappings → should be broad_mappings
   - crm:E42_Identifier was exact_mappings → should be broad_mappings
3. Verified correct Wikidata mappings:
   - Q27032435 (academic archive) → AcademicArchive (exact) ✓
   - Q38723 (higher education institution) → AcademicInstitution (exact) ✓
   - Q9388534 (archival collection) → CampusDocumentationCollection (related) ✓
4. Conceptual model clarification:
   - AcademicArchive = the institution (organizational entity)
   - AcademicArchiveRecordSetType = the classification of record sets
Accomplished
Fully Processed Class Files (25 files)
All with: dictionary-style descriptions, 7-language alt_descriptions, 7-language structured_aliases, proper examples, keywords, correct mapping categories, verified Wikidata mappings
| File | Key Mappings |
|------|--------------|
| AcademicArchive.yaml | wd:Q27032435 (exact), wd:Q166118 (broad) |
| AcademicArchiveRecordSetType.yaml | wd:Q27032435 (close), rico:RecordSetType (broad) |
| AcademicArchiveRecordSetTypes.yaml | 4 subclasses, rico-rst mappings |
| AcademicInstitution.yaml | wd:Q38723 (exact), wd:Q4671277 (close) |
| AcademicProgram.yaml | schema:EducationalOccupationalProgram (exact), wd:Q600134 (close) |
| Access.yaml | dcterms:RightsStatement (exact) |
| AccessApplication.yaml | schema:Action (broad) |
| AccessControl.yaml | schema:DigitalDocumentPermission (close) |
| AccessibilityFeature.yaml | schema:LocationFeatureSpecification (close) |
| AccessInterface.yaml | dcat:DataService (broad) |
| AccessionEvent.yaml | crm:E63_Beginning_of_Existence (broad) |
| AccessionNumber.yaml | crm:E42_Identifier (broad), rico:Identifier (broad) |
| AccessLevel.yaml | skos:Concept (broad) |
| AccessTriggerEvent.yaml | prov:Activity (broad) |
| AccountIdentifier.yaml | schema:PropertyValue (broad) |
| AccountStatus.yaml | skos:Concept (broad) |
| Accreditation.yaml | schema:Permit (broad) |
| AccreditationBody.yaml | schema:Organization (broad) |
| AccreditationEvent.yaml | prov:Activity (broad) |
| Accumulation.yaml | rico:AccumulationRelation (exact) |
| AccuracyLevel.yaml | skos:Concept (broad) |
| Acquisition.yaml | crm:E8_Acquisition (exact) |
| AcquisitionEvent.yaml | crm:E10_Transfer_of_Custody (exact) |
| AcquisitionMethod.yaml | crm:E55_Type (broad) |
Rules Created (6 new/updated)
- class-description-quality-rule.md
- class-multilingual-support-rule.md
- linkml-yaml-best-practices-rule.md
- mapping-specificity-hypernym-rule.md (updated)
- wikidata-mapping-verification-rule.md
- wikidata-mapping-discovery-rule.md (updated)
Remaining Work
- Continue processing remaining class files in /Users/kempersc/apps/glam/schemas/20251121/linkml/modules/classes/
- Fix LSP errors in CollectionType.yaml, UniversityArchiveRecordSetTypes.yaml, AccessPolicy.yaml (duplicate keys)
Relevant files / directories
Directories
- Classes: /Users/kempersc/apps/glam/schemas/20251121/linkml/modules/classes/ (~1,378 YAML files)
- Rules: /Users/kempersc/apps/glam/.opencode/rules/ (47 rule files)
- Ontology data: /Users/kempersc/apps/glam/data/ontology/ (RDF/RDFS/OWL files)
Key Processed Class Files
- AcademicArchive.yaml
- AcademicArchiveRecordSetType.yaml
- AcademicArchiveRecordSetTypes.yaml (contains 4 subclasses)
- AcademicInstitution.yaml
- AcademicProgram.yaml
- Access.yaml through AcquisitionMethod.yaml (20 Access/Accr/Acq files)
Rules Created/Updated This Session
- class-description-quality-rule.md
- class-multilingual-support-rule.md
- linkml-yaml-best-practices-rule.md
- mapping-specificity-hypernym-rule.md
- wikidata-mapping-verification-rule.md
- wikidata-mapping-discovery-rule.md
Files with LSP Errors (need fixing)
- CollectionType.yaml (line 81 - duplicate key)
- UniversityArchiveRecordSetTypes.yaml (lines 51, 86, 119 - duplicate keys)
- AccessPolicy.yaml (lines 129, 133, 184 - duplicate require: keys)

Do not refer to the class itself in the exact mappings. Prevent referring to the terms in the class label when describing it under the description header. 

'Archive' referring classes that do not have recordType in their label almost always refer to the archive as an organisation, please emphasize this in their descriptions.

Never remove structured data represented as string: properly structuralise it using the LinkML conventions and syntax instead. We do need to keep structured data out of the description, but try to preserve it as structured LinkML data. See https://linkml.io/linkml/
REMEMBER THAT MAPPING HALLUCINATED CLASSES OR PREDICATES OR QID IS STRICTLY PROHIBITED! Always double check the Link mappings and the mappings categories (https://linkml.io/linkml-model/latest/docs/mappings/) through studying @data/ontology/ and Wikidata (using the Wikidata MCP) carefully! Continue with: