kempersc 13938c92ca chore(schemas): sync LinkML schemas to frontend apps

Copies authoritative schemas from schemas/20251121/ to:
- frontend/public/schemas/20251121/
- apps/archief-assistent/public/schemas/20251121/

This ensures slot definitions with corrected ontology property
references (commit 2808dad6cd) are available to frontend apps.

2026-01-10 15:02:25 +01:00

14 KiB

Raw Blame History

Conceptual Correction: OrganizationObservation Emic/Etic Clarification

Date: 2025-11-21
Issue: Incorrect characterization of OrganizationObservation as exclusively emic
Resolution: Clarified that observations can be BOTH emic and etic; added OrganizationName subclass for standardized emic names

❌ Previous (Incorrect) Understanding

Old description (WRONG):

"An organization observation represents how a heritage organization is recorded in a specific source. This is the EMIC (insider) perspective: the name and characteristics as they appear in the source..."

Problem: This incorrectly implied that ALL OrganizationObservations are emic (insider perspective). In reality, observations can come from BOTH emic (insider) and etic (outsider) sources.

✅ Corrected Understanding

Three-Level Model

OrganizationObservation (ANY source - emic OR etic)
  ├─ Emic observations: organization's own website, legal documents, official statements
  ├─ Etic observations: guidebooks, academic papers, external descriptions
  │
  └─ OrganizationName (subclass) - STANDARDIZED EMIC perspective only
       └─ The official name the organization accepts for itself
       └─ Distinct from vernacular emic (e.g., "Rijks") and all etic references

OrganizationReconstruction (formal entity)
  └─ Legal entity derived from ALL observations (emic + etic)

Key Distinctions

Class	Perspective	Examples
OrganizationObservation	Emic OR Etic	"Rijks" (emic), "The Rijksmuseum in Amsterdam" (etic), "Rijksmuseum" (ISIL registry, emic)
OrganizationName (subclass)	Emic ONLY (standardized)	"Rijksmuseum" (official self-identification from organizational statutes/website)
OrganizationReconstruction	Entity (derived from all observations)	Stichting Rijksmuseum (legal entity, KvK #41208408)

🔄 Schema Changes Made

1. Updated OrganizationObservation Description

File: schemas/20251121/linkml/02_organization_observation_reconstruction.yaml

New description (lines 60-83):

OrganizationObservation:
  description: >-
    An organization observation represents how a heritage organization is recorded 
    in a specific source. Observations can capture BOTH emic (insider) and etic 
    (outsider) perspectives as they appear in different sources.
    
    Organization observations record names and characteristics exactly as found in sources:
    - Vernacular names (e.g., "Rijks" for Rijksmuseum) - EMIC source
    - Historical spellings (e.g., "Koninklijk Kabinet van Schilderijen") - EMIC/ETIC
    - Abbreviations and acronyms (e.g., "BnF" for Bibliothèque nationale de France) - EMIC
    - Translated names in different languages - ETIC source
    - Third-party references (e.g., guidebook mentions, research papers) - ETIC source
    - Official names in legal documents - EMIC source
    
    IMPORTANT DISTINCTION:
    - OrganizationObservation = ANY recorded reference (emic OR etic)
    - OrganizationName (subclass) = Standardized EMIC name accepted by the organization itself

2. Added OrganizationName Subclass

New class (lines 117-171):

OrganizationName:
  is_a: OrganizationObservation  # Inherits from observation
  class_uri: heritage:OrganizationName
  description: >-
    A specialized subclass of OrganizationObservation that represents the 
    STANDARDIZED EMIC (insider) name - the official or majority-accepted label 
    that the custodian organization uses to identify itself.
    
    This is distinct from generic OrganizationObservation in that it specifically 
    captures the name that the organization ITSELF recognizes and accepts, rather 
    than how external sources might refer to it.
    
    Key characteristics:
    - Officially accepted by the organization (via statutes, website, letterhead)
    - Represents the organization's self-identification
    - Standardized form used for consistent reference
    - May evolve over time (tracked via valid_from/valid_to)

New slots:

standardized_name (required): The canonical emic name
endorsement_source (required): Proof of organizational acceptance
name_authority: Who authorized this name
valid_from / valid_to: Temporal validity
supersedes / superseded_by: Name change history

🔄 Additional Correction: Legal Name vs Legal Form (2025-11-21)

❌ Previous (Conflated) Understanding

Problem: The schema conflated THREE separate concepts:

Operational name (emic, daily use)
Legal registered name (legal documents)
Legal form code (ISO 20275 classification)

Old pattern (WRONG):

legal_name: "Stichting Rijksmuseum"  # Contains both legal form prefix AND name
legal_form: STICHTING  # Generic string, not internationally standardized

✅ Corrected Understanding: Three-Way Distinction

1. Operational Name (OrganizationName.standardized_name)
   - "Rijksmuseum"
   - Used in daily operations (website, signage, marketing, PR)
   - The EMIC name the organization actively identifies with

2. Legal Registered Name (org:legalName)
   - "Stichting Rijksmuseum"
   - Appears in legal documents, statutes, KvK registry
   - The FORMAL name for legal transactions
   - Often includes legal form prefix/suffix

3. Legal Form Code (org:classification)
   - "V44D" (ISO 20275 ELF code)
   - International standard for legal entity types
   - NOT a name - it's a CLASSIFICATION CODE
   - Reference: /data/ontology/2023-09-28-elf-code-list-v1.5.csv

Real-World Examples

Institution	Operational Name	Legal Registered Name	Legal Form Code
Rijksmuseum	Rijksmuseum	Stichting Rijksmuseum	V44D (NL stichting)
Getty Museum	Getty Museum	J. Paul Getty Trust	(US trust code)
British Museum	British Museum	The Trustees of the British Museum	9HLU (UK charity)
BnF	Bibliothèque nationale de France	Établissement public Bibliothèque nationale de France	5RDO (FR établissement public)

Schema Changes Made

File: schemas/20251121/linkml/02_organization_observation_reconstruction.yaml

Updated descriptions:

legal_name slot (lines 308-324):

legal_name:
  description: >-
    The official legal name under which the organization is registered with 
    government authorities (e.g., "Stichting Rijksmuseum" in Dutch KvK registry).
    
    CRITICAL: This is the LEGAL REGISTERED NAME, which may differ from the 
    operational/emic name (e.g., operational "Rijksmuseum" vs legal "Stichting 
    Rijksmuseum").
    
    This legal name often includes the legal form as a prefix/suffix but is 
    still a NAME, not a classification code. For the legal form CODE, use the 
    legal_form slot with ISO 20275 ELF codes.

legal_form slot (lines 326-347):

legal_form:
  description: >-
    ISO 20275 Entity Legal Forms (ELF) Code specifying the legal form/type of 
    the organization (e.g., "V44D" for Dutch stichting, "F0A6" for Argentine 
    Sociedad Anonima).
    
    CRITICAL: This is NOT the legal name - it's a CLASSIFICATION CODE per ISO 
    20275 international standard maintained by GLEIF (Global Legal Entity 
    Identifier Foundation).
    
    The legal_name may CONTAIN words indicating legal form (e.g., "Stichting 
    Rijksmuseum" contains "Stichting"), but legal_form is the FORMAL CODE 
    ("V44D") that classifies the entity type.
    
    See /data/ontology/2023-09-28-elf-code-list-v1.5.csv for complete code list.

Documentation Created

File: schemas/20251121/ISO_20275_ELF_MAPPING.md

Complete guide including:

ISO 20275 ELF code overview
Netherlands legal forms for heritage institutions (21 codes)
International examples (France, Germany, Italy, Spain, UK, USA, Japan, etc.)
Migration path from generic enums to ISO 20275
W3C Org Ontology alignment (org:legalName, org:classification)

3. Updated Notes Section

Old notes (WRONG):

notes:
  - "Emic perspective: 'how we call ourselves' or 'how source refers to us'"

New notes (CORRECT):

notes:
  - "Can represent BOTH emic (insider) and etic (outsider) perspectives"
  - "Multiple observations (emic + etic) can link to one reconstruction (entity)"
  - "Examples: 'Rijks' (emic observation), 'The Rijksmuseum in Amsterdam' (etic observation)"
  - "See OrganizationName subclass for standardized emic name specifically"

📝 Updated Example File

File: schemas/20251121/examples/rijksmuseum_observation_reconstruction.yaml

New structure:

observations:
  # EMIC observation - vernacular
  - id: .../rijks-website-2024
    observed_name: "Rijks"
    observation_context: "Website branding - EMIC vernacular usage"
  
  # ETIC observation - guidebook
  - id: .../rijks-guidebook-2023
    observed_name: "The Rijksmuseum in Amsterdam"
    observation_context: "Tourist guidebook - ETIC external description"
  
  # EMIC observation - ISIL registry
  - id: .../rijks-isil-2020
    observed_name: "Rijksmuseum"
    observation_context: "ISIL registry - EMIC official entry"
  
  # ETIC observation - academic paper
  - id: .../rijks-paper-2022
    observed_name: "Rijksmuseum Amsterdam"
    observation_context: "Academic paper - ETIC scholarly reference"

standardized_name:
  # STANDARDIZED EMIC name (subclass)
  - id: .../rijksmuseum-standard
    type: OrganizationName
    standardized_name: "Rijksmuseum"
    endorsement_source: "https://www.rijksmuseum.nl/en/about-us"
    name_authority: "Board of Trustees resolution, 2013"

reconstruction:
  # Formal entity derived from ALL observations
  - id: .../org/rijksmuseum
    type: OrganizationReconstruction
    legal_name: "Stichting Rijksmuseum"
    was_derived_from:
      - .../rijks-website-2024  # emic
      - .../rijks-guidebook-2023  # etic
      - .../rijks-isil-2020  # emic
      - .../rijks-paper-2022  # etic
      - .../rijksmuseum-standard  # standardized emic

🔍 Why This Matters

1. Accurate Modeling of Sources

Before: We could only model emic (insider) observations
After: We can model observations from ANY source (insider OR outsider)

2. Distinguishes Standardization

Before: No clear way to mark which emic name is "official"
After: OrganizationName subclass captures the standardized emic name specifically

3. Supports Full Provenance

Before: Unclear how external references (etic) fit into the model
After: All observations (emic + etic) feed into entity reconstruction

4. Aligns with PiCo Pattern

PiCo (Persons in Context) also recognizes that observations can be:

Emic: How a person identifies themselves
Etic: How others identify the person

Our model now properly mirrors this distinction for organizations.

📊 Real-World Example: Rijksmuseum

Multiple Observations (Emic + Etic)

Source Type	Observation	Perspective
Emic	Official website: "Rijks" (vernacular)	Insider informal
Emic	ISIL registry: "Rijksmuseum"	Insider official
Emic	KvK registry: "Stichting Rijksmuseum"	Insider legal
Etic	Guidebook: "The Rijksmuseum in Amsterdam"	Outsider descriptive
Etic	Academic paper: "Rijksmuseum Amsterdam"	Outsider scholarly

Standardized Emic Name (ONE)

OrganizationName: "Rijksmuseum"

Endorsed by: Board of Trustees resolution (2013)
Source: Official organizational website
Authority: Organizational self-identification

Reconstruction (ONE Entity)

OrganizationReconstruction: Stichting Rijksmuseum

Legal form: Stichting (Dutch foundation)
KvK: 41208408
ISIL: NL-AmRMA
Derived from: All 5 observations above + standardized name

✅ Implementation Checklist

Updated OrganizationObservation description
Added OrganizationName subclass
Added new slots (standardized_name, endorsement_source, etc.)
Updated notes to reflect emic/etic distinction
Rewrote example file with corrected model
Regenerated RDF/OWL files from updated schema
Updated README.md (partial - needs completion)
Updated RDF_GENERATION_SUMMARY.md (needs update)
Update Mermaid diagrams to show OrganizationName subclass
Update PlantUML diagrams to show three-level hierarchy
Update TypeDB schema with new entity type
Create SHACL shapes for OrganizationName validation

🔄 Migration Notes

For Existing Data

If you have existing OrganizationObservation instances:

Review source type: Is the observation from an emic or etic source?
Add context: Update observation_context to clarify perspective
Identify standardized name: If the observation represents the organization's official name, consider creating an OrganizationName instance instead

For New Data

Start with observations: Collect all emic AND etic references
Identify standardized name: Find the official organizational self-identification
Create OrganizationName: Use subclass for the standardized emic name
Reconstruct entity: Derive formal entity from all observations

📚 References

PiCo (Persons in Context): https://personsincontext.org/
- PersonObservation vs. PersonReconstruction pattern
- Emic/etic distinction for person identification
PROV-O: https://www.w3.org/TR/prov-o/
- wasDerivedFrom: Linking observations to reconstructions
- wasGeneratedBy: Documenting entity resolution process
CIDOC-CRM E41 Appellation: http://www.cidoc-crm.org/
- Names as distinct from entities they identify

Corrected by: GLAM Ontology Project
Date: 2025-11-21
Impact: Critical conceptual correction affecting all organization modeling

14 KiB Raw Blame History