id: https://nde.nl/ontology/hc/class/Identifier
name: identifier_classes
title: Identifier Classes (Generic and Custodian-Specific)
# Updated: 2026-01-23 - Added has_or_had_type for IdentifierType per F26 migration
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  crm: http://www.cidoc-crm.org/cidoc-crm/
  schema: http://schema.org/
  skos: http://www.w3.org/2004/02/skos/core#
  dcterms: http://purl.org/dc/terms/
  adms: http://www.w3.org/ns/adms#
  prov: http://www.w3.org/ns/prov#
imports:
  - linkml:types
  - ../metadata
  - ../slots/has_or_had_canonical_form
  - ../slots/has_or_had_format
  - ../slots/has_or_had_scheme
  - ../slots/has_or_had_score
  - ../slots/has_or_had_standard
  - ../slots/has_or_had_type
  - ../slots/has_or_had_value
  - ../slots/identifies_or_identified
  - ../slots/is_or_was_allocated_by
  - ../slots/is_or_was_allocated_through
  - ../slots/source
  - ../slots/temporal_extent
default_prefix: hc
classes:
  # Generic Identifier class - base for all identifier types
  Identifier:
    class_uri: schema:PropertyValue
    description: |
      A generic identifier consisting of a scheme and value pair.
      **Purpose**:
      Base identifier class for any entity (not just heritage custodians).
      Used when a simple scheme + value identifier is needed.
      **For heritage custodian identifiers**: Use `CustodianIdentifier` which
      extends this class with provenance tracking (allocation agency, standard, etc.)
      **Schema.org Alignment**:
      Maps to schema:PropertyValue which represents a property-value pair.
      - propertyID → identifier_scheme
      - value → identifier_value
    exact_mappings:
      - schema:PropertyValue
    close_mappings:
      - dcterms:identifier
      - adms:Identifier
      - skos:notation
    slots:
    # identifier_scheme REMOVED - migrated to has_or_had_scheme (Rule 53)
    - has_or_had_scheme
    # identifier_value REMOVED - migrated to has_or_had_value (Rule 53)
    - has_or_had_value
    - has_or_had_type
    slot_usage:
      has_or_had_type:
        range: IdentifierType
        required: false
        examples:
        - value:
            has_or_had_code: CATALOG_RAISONNE
            has_or_had_label: Catalogue Raisonné Number
        - value:
            has_or_had_code: ISIL
            has_or_had_label: ISIL Code
      has_or_had_scheme:
        range: IdentifierScheme
        inlined: true
        examples:
        - value:
            has_or_had_label: "ISBN"
      has_or_had_value:
        range: IdentifierValue
        inlined: true
        examples:
        - value:
            has_or_had_value: "978-0-123456-47-2"
        required: false
    annotations:
      specificity_score: 0.25
      specificity_rationale: |
        Low specificity - identifiers are broadly useful across all queries
        involving entity lookup and cross-referencing.
  # Heritage custodian-specific identifier with provenance tracking
  CustodianIdentifier:
    is_a: Identifier
    class_uri: crm:E42_Identifier
    description: |
      An external identifier assigned to a heritage custodian entity by an authority.
      Extends the generic Identifier class with provenance tracking:
      - Which authority allocated the identifier
      - Under what standard it was assigned
      - When it was allocated
      - Canonical/normalized form for matching
      Connected to the Custodian hub via inverse property crm:P48i_is_preferred_identifier_of
      (the Custodian has this Identifier as a preferred identifier).
      CIDOC-CRM E42_Identifier: Formal symbols or reference codes for unique identification.
      CIDOC-CRM P48_has_preferred_identifier: Links E1_CRM_Entity (Custodian) to E42_Identifier.
      **Use for**: 
      - External authority identifiers (ISIL, Wikidata, VIAF, KvK, ROR)
      - Registration numbers and codes
      - Persistent identifiers from registries
      **Connection to Hub**:
      - The Custodian hub uses crm:P48_has_preferred_identifier to point to CustodianIdentifier
      - This CustodianIdentifier uses crm:P48i_is_preferred_identifier_of to point back to the Custodian hub
      - Enables multiple identifiers per custodian (from different authorities)
      **Extended Provenance (v2)**:
      The identifier now tracks its full lineage:
      - has_or_had_standard: Which Standard defines this identifier type (ISIL → ISO 15511)
      - allocated_by: Which AllocationAgency assigned this specific identifier
      - identifier_format_used: Which format variant is used in identifier_value
      - has_or_had_canonical_form: Normalized form (CanonicalForm) for deduplication and matching
      - allocation_date: When the identifier was assigned
      **Dual-Purpose Identifiers**:
      Some identifiers (ISNI, VIAF) also identify name authority records:
      - has_or_had_secondary_label: Links to the CustodianName record this identifier also identifies (as a Label)
      **Enables**:
      - External identifier management (scheme + value)
      - Cross-reference to authority registries
      - Persistent identifier resolution
      - Inter-dataset linking
      - Full provenance tracking (who allocated, when, under what standard)
      - Name authority linkage (for ISNI, VIAF)
    exact_mappings:
      - crm:E42_Identifier
    close_mappings:
      - schema:identifier
      - adms:Identifier
      - skos:notation
    related_mappings:
      - owl:sameAs
    slots:
      - is_or_was_allocated_by
      - is_or_was_allocated_through
    slot_usage:
      is_or_was_allocated_through:
        range: AllocationEvent
        examples:
        - value:
            temporal_extent:
              begin_of_the_begin: "2023-01-01"
      # MIGRATED 2026-01-24: defined_by_standard → has_or_had_standard + Standard (Rule 53)
      has_or_had_standard:
        range: string
        required: false
        multivalued: false
        inlined: false
        examples:
          - value:
              name: "International Standard Identifier for Libraries"
      is_or_was_allocated_by:
        required: false
      has_or_had_canonical_form:
        range: CanonicalForm
        required: false
        multivalued: false
        inlined: true
      # identifies_custodian REMOVED - migrated to identifies_or_identified (Rule 53)
      identifies_or_identified:
        range: Custodian
        required: false
    annotations:
      specificity_score: 0.30
      specificity_rationale: |
        Slightly higher specificity than generic Identifier due to
        heritage custodian-specific provenance tracking.