id: https://nde.nl/ontology/hc/class/SourceCommentCount
name: source_comment_count_class
title: Source Comment Count Class

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

imports:
- linkml:types
- ../metadata
- ../slots/has_or_had_quantity
- ../slots/was_fetched_at
- ./Quantity
- ./Timestamp
default_prefix: hc

classes:
  SourceCommentCount:
    class_uri: hc:SourceCommentCount
    description: |
      Comment count metadata from an external source (API, web page).
      
      **PURPOSE**:
      
      Structured representation of comment retrieval metadata, tracking
      how many comments were fetched versus the total available at the source.
      Replaces simple integer count with rich provenance data.
      
      **DESIGN RATIONALE**:
      
      Created per slot_fixes.yaml migration from `comments_fetched` integer
      to structured `was_fetched_at` + `Timestamp` + `is_or_was_part_of_total`
      + `SourceCommentCount` for complete retrieval tracking.
      
      **USE CASES**:
      
      - YouTube API: Track fetched comments vs total comment count
      - Social media: Partial comment retrieval with pagination
      - Web scraping: Track scraped vs visible comments
      
      **EXAMPLE**:
      
      ```yaml
      is_or_was_part_of_total:
        fetched_count: 100
        total_count: 500
        fetch_complete: false
        was_fetched_at:
          has_or_had_timestamp: "2025-01-14T10:30:00Z"
      ```
    
    close_mappings:
      - schema:InteractionCounter
      - prov:Entity
    
    slots:
      - was_fetched_at
      - has_or_had_quantity
    
    attributes:
      fetched_count:
        description: |
          Number of items actually fetched/retrieved.
        range: integer
        required: true
        minimum_value: 0
        examples:
          - value: 100
            description: 100 comments fetched
      
      total_count:
        description: |
          Total number of items available at the source.
          May be null if source doesn't provide total.
        range: integer
        required: false
        minimum_value: 0
        examples:
          - value: 500
            description: 500 total comments at source
      
      fetch_complete:
        description: |
          Whether all available items were fetched.
          True if fetched_count equals total_count.
        range: boolean
        required: false
        ifabsent: "false"
        examples:
          - value: true
            description: All comments fetched
          - value: false
            description: Partial fetch
      
      source_api:
        description: |
          API or source from which data was fetched.
        range: string
        required: false
        examples:
          - value: "youtube_data_api_v3"
            description: YouTube Data API
          - value: "web_scrape"
            description: Web scraping
    
    slot_usage:
      was_fetched_at:
        range: Timestamp
        inlined: true
        required: false
        examples:
          - value:
              has_or_had_timestamp: "2025-01-14T10:30:00Z"
      has_or_had_quantity:
        range: integer
        inlined: true
        required: false
    
    examples:
      - value:
          was_fetched_at:
            has_or_had_timestamp: "2025-01-14T10:30:00Z"
      - value:
      - value:
    comments:
      - Created 2026-01-22 from comments_fetched migration (Rule 53)
      - Tracks fetched vs total comment counts
      - Includes fetch timestamp for provenance
      - Supports partial/paginated data retrieval
    
    see_also:
      - https://schema.org/InteractionCounter
    
    annotations:
      custodian_types: '["*"]'
      custodian_types_rationale: >-
        Universal - any custodian with video/social media content.
      specificity_score: "0.70"
      specificity_rationale: >-
        Specific to video/social media comment fetching contexts.