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:

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:

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?

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

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