# URL class
# Structured URL representation with type and metadata
#
# Generation date: 2026-01-15
# Rule compliance: 0 (LinkML single source of truth), 38 (slot centralization), 53 (slot_fixes.yaml)
#
# This class supports 4 slot migrations per slot_fixes.yaml:
# - website → has_or_had_url + URL
# - url → has_or_had_url + URL
# - vendor_url → has_or_had_url + URL
# - was_archived_at → is_or_was_webarchived_at + URL

id: https://nde.nl/ontology/hc/class/URL
name: url_class
title: URL Class

prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  schema: http://schema.org/
  dcterms: http://purl.org/dc/terms/
  prov: http://www.w3.org/ns/prov#

default_prefix: hc

imports:
  - linkml:types
  - ../metadata
  # RiC-O style generic slots - migrated 2026-01-16 per Rule 53
  - ../slots/has_or_had_url       # was: url_value
  - ../slots/has_or_had_type      # was: url_type
  - ../slots/language
  - ../slots/specificity_annotation
  - ../slots/has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
  - ./SpecificityAnnotation
  - ./TemplateSpecificityScore  # was: TemplateSpecificityScores - migrated per Rule 53 (2026-01-17)

  - ./TemplateSpecificityType

  - ./TemplateSpecificityTypes

classes:
  URL:
    class_uri: schema:URL
    description: |
      Structured representation of a URL with type classification and metadata.
      
      **Purpose**:
      URL provides a reusable class for representing web addresses with
      additional context about what type of URL it is (website, API, archive, etc.)
      and optional language/locale information.
      
      **Ontological Alignment**:
      - **Primary**: `schema:URL` - Schema.org URL datatype
      - **Close**: `dcterms:URI` - Dublin Core URI
      - **Related**: `prov:Entity` - Provenance entity (for archived URLs)
      
      **Use Cases**:
      - Institution websites: `has_or_had_url` with type "website"
      - API endpoints: `has_or_had_url` with type "api"
      - Web archive snapshots: `is_or_was_webarchived_at` with archive URL
      - Vendor/supplier sites: `has_or_had_url` with type "vendor"
      
      **Replaces** (per slot_fixes.yaml):
      - `website` (simple string URL)
      - `url` (simple string URL)
      - `vendor_url` (simple string URL)
      - `was_archived_at` (simple string URL)
      
    exact_mappings:
      - schema:URL
    
    close_mappings:
      - dcterms:URI
    
    related_mappings:
      - prov:Entity
    
    slots:
      - has_or_had_url         # was: url_value - migrated 2026-01-16 per Rule 53
      - has_or_had_type        # was: url_type - migrated 2026-01-16 per Rule 53
      - language
      - specificity_annotation
      - has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
    
    slot_usage:
      has_or_had_url:  # was: url_value - migrated 2026-01-16 per Rule 53
        description: |
          The actual URL string (e.g., https://example.org/).
        range: uri
        required: true
      has_or_had_type:  # was: url_type - migrated 2026-01-16 per Rule 53
        description: |
          Classification of the URL type (website, api, archive, etc.).
        range: string
        required: false
      language:
        description: |
          Language/locale of the content at this URL.
          ISO 639-1 code, optionally with region (e.g., "en", "nl-NL").
        range: string
        required: false
        pattern: "^[a-z]{2}(-[A-Z]{2})?$"
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: URLs apply to all heritage custodian types.
      custodian_types_primary: null
      specificity_score: 0.15
      specificity_rationale: Generic URL class applicable across all contexts.
    
    examples:
      - value: |
          has_or_had_url: "https://www.rijksmuseum.nl/"
          has_or_had_type: website
          language: nl
        description: "Official website URL for Rijksmuseum"
      - value: |
          has_or_had_url: "https://api.rijksmuseum.nl/api/nl/collection"
          has_or_had_type: api
          language: nl
        description: "API endpoint for Rijksmuseum collection"
      - value: |
          has_or_had_url: "https://web.archive.org/web/20240101/https://example.org/"
          has_or_had_type: webarchive
        description: "Web archive snapshot URL"