glam/.opencode/rules/linkml/wikidata-mapping-discovery-rule.md

# Wikidata Mapping Discovery Rule

## Rule: Use Wikidata MCP to Discover and Verify Mappings Carefully

When adding Wikidata mappings to class files, you MUST verify the semantic meaning and relationship before adding any mapping.

### 🚨 CRITICAL: Always Verify Before Adding

**NEVER add a Wikidata QID without verifying:**
1. What the entity actually IS (not just the label)
2. That it's the SAME TYPE as your class (organization→organization, NOT organization→building)
3. That the semantic relationship makes sense

### Workflow

#### Step 1: VERIFY Existing Mappings First

Before trusting any existing mapping, verify it:

```sparql
SELECT ?item ?itemLabel ?itemDescription WHERE {
  VALUES ?item { wd:Q22075301 wd:Q1643722 wd:Q185583 }
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}
```

**Example of WRONG mappings found in codebase:**
| QID | Label | Was Mapped To | WHY WRONG |
|-----|-------|---------------|-----------|
| Q22075301 | textile artwork | FacultyPaperCollection | Not related at all! |
| Q1643722 | building in Vienna | UniversityAdministrativeFonds | Not an archival concept! |
| Q185583 | candy | AcademicStudentRecordSeries | Completely unrelated! |

#### Step 2: Search for Candidates

Search for relevant Wikidata entities by keyword or hierarchy:

```sparql
SELECT ?item ?itemLabel ?itemDescription WHERE {
  ?item wdt:P279 wd:Q166118 .  # subclasses of "archives"
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}
```

#### Step 3: VERIFY Each Candidate

For EVERY candidate found, verify:
1. **Read the description** - does it match your class?
2. **Check instance of (P31)** - is it the same type?
3. **Check subclass of (P279)** - is it in a relevant hierarchy?

```sparql
SELECT ?item ?itemLabel ?itemDescription ?instanceLabel ?subclassLabel WHERE {
  VALUES ?item { wd:Q9388534 }
  OPTIONAL { ?item wdt:P31 ?instance. }
  OPTIONAL { ?item wdt:P279 ?subclass. }
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
}
```

#### Step 4: Confirm Semantic Relationship

Ask: **Would a domain expert agree this mapping makes sense?**

| Your Class | Wikidata Entity | Verdict |
|------------|-----------------|---------|
| FacultyPaperCollection | Q22075301 (textile artwork) | ❌ NO - completely unrelated |
| CampusDocumentationCollection | Q9388534 (archival collection) | ✅ YES - semantically related |
| AcademicArchive | Q27032435 (academic archive) | ✅ YES - exact match |

### Type Compatibility Rules

| Your Class Type | Valid Wikidata Types | Invalid Wikidata Types |
|-----------------|---------------------|------------------------|
| Organization | organization, institution | building, person, artwork |
| Record Set Type | collection, fonds, series | building, candy, textile |
| Event | activity, occurrence | organization, place |
| Type/Category | type, concept, class | specific instances |

### Common Mistakes to Avoid

❌ **WRONG: Adding any QID found in search without verification**
```
"Found Q1643722 in search results, adding it as mapping"
→ Result: Mapping a "building in Vienna" to "UniversityAdministrativeFonds"
```

✅ **CORRECT: Verify description and type before adding**
```
1. Search finds Q1643722
2. Verify: Q1643722 = "building in Vienna, Austria"
3. Check: Is a building related to "UniversityAdministrativeFonds"?
4. Decision: NO - do not add this mapping
```

### When to Add Wikidata Mappings

Add Wikidata mappings ONLY when:
- [ ] You verified the entity's label AND description
- [ ] The entity is the same type as your class
- [ ] The semantic relationship is clear (exact, broader, narrower, related)
- [ ] A domain expert would agree the mapping makes sense

### When NOT to Add Wikidata Mappings

Do NOT add Wikidata mappings when:
- You only searched but didn't verify the description
- The entity type doesn't match (e.g., building vs. organization)
- The relationship is unclear or forced
- You're just trying to "fill in" mappings

### Mapping Categories

| Category | Wikidata Property | When to Use |
|----------|-------------------|-------------|
| `exact_mappings` | - | Same semantic meaning (rare!) |
| `close_mappings` | - | Similar but not identical |
| `broad_mappings` | P279 (subclass of) | Wikidata entity is BROADER |
| `narrow_mappings` | inverse of P279 | Wikidata entity is NARROWER |
| `related_mappings` | - | Non-hierarchical but semantically related |

### Checklist

For each Wikidata mapping:

- [ ] Verified entity label matches expected meaning
- [ ] Verified entity description confirms semantic fit
- [ ] Entity type is compatible with class type
- [ ] Mapping category (exact/close/broad/narrow/related) is correct
- [ ] A domain expert would agree this makes sense

### Example: Proper Verification for FacultyPaperCollection

**Step 1: What are we looking for?**
- Personal papers of faculty members
- Academic archives
- Manuscript collections

**Step 2: Search**
```sparql
SELECT ?item ?itemLabel ?itemDescription WHERE {
  ?item ?prop ?value .
  ?value bif:contains "'personal papers' OR 'faculty papers'" .
  SERVICE wikibase:label { bd:serviceParam wikibase:language "en". }
} LIMIT 10
```

**Step 3: Verify candidates**
- If no exact match found → DO NOT add a wrong mapping
- Better to have NO Wikidata mapping than a WRONG one

**Step 4: Decision**
- No exact Wikidata match for "FacultyPaperCollection"
- Keep ontology mappings only (rico-rst:Fonds, bf:Archival)
- Do NOT add unrelated QIDs like Q22075301 (textile artwork!)

### Integration with Other Rules

This rule complements:
- **mapping-specificity-hypernym-rule.md**: Rules for choosing mapping type
- **wikidata-mapping-verification-rule.md**: Rules for verifying QIDs exist
- **verified-ontology-mapping-requirements.md**: General ontology verification