id: https://nde.nl/ontology/hc/class/VideoChapter
name: video_chapter_class
title: Video Chapter Class
imports:
  - linkml:types
  - ./VideoTimeSegment
  - ../slots/specificity_annotation
  - ./SpecificityAnnotation
  - ../slots/has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
  - ./TemplateSpecificityScore  # was: TemplateSpecificityScores - migrated per Rule 53 (2026-01-17)

  - ./TemplateSpecificityType

  - ./TemplateSpecificityTypes
  - ./AutoGeneration  # Added for is_or_was_created_through migration (2026-01-15)
  - ../enums/ChapterSourceEnum
  - ../slots/is_or_was_created_through  # MIGRATED: was ../slots/auto_generated (2026-01-15)
  - ../slots/chapter_description
  - ../slots/chapter_end_seconds
  - ../slots/chapter_end_time
  - ../slots/chapter_id
  - ../slots/chapter_index
  - ../slots/chapter_source
  - ../slots/chapter_start_seconds
  - ../slots/chapter_start_time
  # REMOVED 2026-01-18: ../slots/chapter_thumbnail_url - migrated to has_or_had_thumbnail + Thumbnail (Rule 53)
  # REMOVED 2026-01-19: ../slots/chapter_thumbnail_timestamp - migrated to Thumbnail.has_or_had_time_interval (Rule 53)
  - ../slots/has_or_had_thumbnail  # was: chapter_thumbnail_url - migrated per Rule 53 (2026-01-18)
  - ./Thumbnail  # Updated 2026-01-19: now includes derives_or_derived_from and has_or_had_time_interval
  - ./Video  # Added 2026-01-19: for Thumbnail.derives_or_derived_from
  - ./TimeInterval  # Added 2026-01-19: for Thumbnail.has_or_had_time_interval
  - ../slots/has_or_had_label  # was: chapter_title - migrated per Rule 53/56 (2026-01-18)
  - ./Label
  - ../slots/nesting_level
  - ../slots/parent_chapter_id
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#
  crm: http://www.cidoc-crm.org/cidoc-crm/
  oa: http://www.w3.org/ns/oa#
  ma: http://www.w3.org/ns/ma-ont#
  wd: http://www.wikidata.org/entity/
default_prefix: hc
classes:
  VideoChapter:
    class_uri: schema:Clip
    abstract: false
    description: "A named chapter or section within a video, defined by temporal boundaries.\n\n**DEFINITION**:\n\nVideoChapter\
      \ represents a titled segment of video content, typically used for\nnavigation and content organization. Chapters appear\
      \ in video player interfaces\n(YouTube chapters, Vimeo chapters) allowing viewers to jump to specific sections.\n\n\
      **PLATFORM SUPPORT**:\n\n| Platform | Chapter Support | Auto-Generated | Custom Thumbnails |\n|----------|-----------------|----------------|-------------------|\n\
      | YouTube | Yes (2020+) | Yes | No (keyframe) |\n| Vimeo | Yes | No | Yes |\n| Facebook | Limited | No | No |\n| Wistia\
      \ | Yes | No | Yes |\n\n**YOUTUBE CHAPTER REQUIREMENTS**:\n\nFor YouTube to recognize chapters:\n- First chapter MUST\
      \ start at 0:00\n- Minimum 3 chapters required\n- Each chapter must be at least 10 seconds\n- Timestamps in description\
      \ in `MM:SS` or `HH:MM:SS` format\n\n**HERITAGE INSTITUTION USE CASES**:\n\n| Content Type | Chapter Examples |\n|--------------|------------------|\n\
      | Virtual tour | \"Main Hall\", \"Dutch Masters\", \"Gift Shop\" |\n| Conservation | \"Assessment\", \"Cleaning\", \"\
      Retouching\", \"Varnishing\" |\n| Interview | \"Introduction\", \"Early Career\", \"Major Works\", \"Legacy\" |\n| Exhibition\
      \ | \"Curator Introduction\", \"Theme 1\", \"Theme 2\", \"Conclusion\" |\n| Lecture | \"Overview\", \"Case Study 1\"\
      , \"Case Study 2\", \"Q&A\" |\n\n**AUTO-GENERATED VS MANUAL CHAPTERS**:\n\n| Source | Characteristics | Quality |\n\
      |--------|-----------------|---------|\n| Manual (creator) | Semantic, meaningful titles | High |\n| YouTube AI | Scene-based,\
      \ generic titles | Variable |\n| Third-party tools | Transcript-based, keyword titles | Medium |\n\nThe `auto_generated`\
      \ flag distinguishes these sources.\n\n**RELATIONSHIP TO VideoTimeSegment**:\n\nVideoChapter USES VideoTimeSegment for\
      \ temporal boundaries rather than\nextending it. This composition pattern allows:\n- Reuse of segment validation (start\
      \ < end)\n- Consistent time representation across schema\n- Separation of structural (chapter) and temporal (segment)\
      \ concerns\n\n**MEDIA FRAGMENTS URI**:\n\nChapters can be addressed via W3C Media Fragments:\n```\nhttps://youtube.com/watch?v=ABC123#t=120,300\n\
      ```\nCorresponds to chapter starting at 2:00, ending at 5:00.\n\n**NESTED CHAPTERS**:\n\nSome platforms support hierarchical\
      \ chapters (parent/child).\nUse `parent_chapter_id` for nested structure:\n\n```\nChapter 1: Dutch Golden Age\n  └─\
      \ 1.1: Rembrandt\n  └─ 1.2: Vermeer\nChapter 2: Modern Art\n```\n"
    exact_mappings:
    - schema:Clip
    close_mappings:
    - ma:MediaFragment
    - crm:E52_Time-Span
    related_mappings:
    - wikidata:Q1454986
    slots:
    - is_or_was_created_through  # MIGRATED: was auto_generated (2026-01-15)
    - chapter_description
    - chapter_end_seconds
    - chapter_end_time
    - chapter_id
    - chapter_index
    - chapter_source
    - chapter_start_seconds
    - chapter_start_time
    # REMOVED 2026-01-19: chapter_thumbnail_timestamp - migrated to Thumbnail.has_or_had_time_interval (Rule 53)
    - has_or_had_thumbnail  # was: chapter_thumbnail_url - migrated per Rule 53 (2026-01-18)
    - has_or_had_label  # was: chapter_title - migrated per Rule 53/56 (2026-01-18)
    - nesting_level
    - parent_chapter_id
    - specificity_annotation
    - has_or_had_score  # was: template_specificity - migrated per Rule 53 (2026-01-17)
    slot_usage:
      chapter_id:
        range: string
        required: true
        examples:
        - value: ABC123_chapter_0
          description: First chapter of video ABC123
        - value: 550e8400-e29b-41d4-a716-446655440000
          description: UUID-based chapter ID
      has_or_had_label:  # was: chapter_title - migrated per Rule 53/56 (2026-01-18)
        description: |
          MIGRATED from chapter_title per slot_fixes.yaml (Rule 53/56, 2026-01-18).
          Title of the chapter as displayed to viewers.
          Uses Label class for structured chapter titles with optional language tagging.
        range: Label
        inlined: true
        required: true
        examples:
        - value: 
            has_or_had_label: De Nachtwacht (The Night Watch)
            language: nl
          description: Chapter about specific artwork
        - value:
            has_or_had_label: "Curator Interview: Conservation Process"
            language: en
          description: Interview segment chapter
      chapter_index:
        range: integer
        required: true
        minimum_value: 0
        examples:
        - value: 0
          description: First chapter
        - value: 5
          description: Sixth chapter (zero-indexed)
      chapter_description:
        range: string
        required: false
        examples:
        - value: Dr. Dibbits discusses the restoration of Rembrandt's masterpiece, including the controversial 2019 operation.
          description: Detailed chapter description
      chapter_start_seconds:
        range: float
        required: true
        minimum_value: 0.0
        examples:
        - value: 0.0
          description: First chapter starts at video beginning
        - value: 120.5
          description: Chapter starts at 2:00.5
      chapter_end_seconds:
        range: float
        required: false
        minimum_value: 0.0
        examples:
        - value: 120.0
          description: Chapter ends at 2:00
      chapter_start_time:
        range: string
        required: false
        pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$
        examples:
        - value: PT0S
          description: Start of video
        - value: PT10M30S
          description: 10 minutes 30 seconds
      chapter_end_time:
        range: string
        required: false
        pattern: ^PT(\d+H)?(\d+M)?(\d+(\.\d+)?S)?$
        examples:
        - value: PT5M0S
          description: 5 minutes
      is_or_was_created_through:  # MIGRATED: was is_auto_generated (2026-01-15)
        description: Whether this chapter was auto-generated by AI/platform algorithms
        range: boolean
        required: false
        examples:
        - value: false
          description: Manual creator-defined chapter
        - value: true
          description: YouTube AI auto-generated
      chapter_source:
        range: ChapterSourceEnum
        required: false
        examples:
        - value: MANUAL
          description: Creator manually added chapters
      has_or_had_thumbnail:  # was: chapter_thumbnail_url - migrated per Rule 53 (2026-01-18)
        description: |
          MIGRATED from chapter_thumbnail_url per slot_fixes.yaml (Rule 53, 2026-01-18).
          UPDATED 2026-01-19: chapter_thumbnail_timestamp now captured via Thumbnail.has_or_had_time_interval.
          
          Thumbnail image for this chapter, used for preview in video players.
          Uses Thumbnail class for structured representation with:
          - URL of the thumbnail image
          - derives_or_derived_from: source Video reference
          - has_or_had_time_interval: frame timestamp as TimeInterval
          
          **Platform Behavior**:
          - YouTube: Auto-selects keyframe from chapter start
          - Vimeo: Allows custom chapter thumbnails
        range: Thumbnail
        inlined: true
        required: false
        examples:
        - value:
            has_or_had_url: "https://i.ytimg.com/vi/ABC123/hq1.jpg"
          description: Simple thumbnail with URL only
        - value:
            has_or_had_url: "https://i.ytimg.com/vi/ABC123/hq1.jpg"
            derives_or_derived_from:
              has_or_had_url: "https://www.youtube.com/watch?v=ABC123"
            has_or_had_time_interval:
              duration_value: "PT2M2.5S"
              duration_description: "Frame at 2:02.5 (was chapter_thumbnail_timestamp: 122.5)"
          description: Thumbnail with source video and timestamp (replaces chapter_thumbnail_timestamp)
      # REMOVED 2026-01-19: chapter_thumbnail_timestamp - migrated to Thumbnail.has_or_had_time_interval (Rule 53)
      parent_chapter_id:
        range: string
        required: false
        examples:
        - value: ABC123_chapter_0
          description: This is a sub-chapter of chapter 0
      nesting_level:
        range: integer
        required: false
        minimum_value: 0
        examples:
        - value: 0
          description: Top-level chapter
        - value: 1
          description: Sub-chapter
    comments:
    - Models video chapters for navigation (YouTube chapters, etc.)
    - Supports both manual and auto-generated chapters
    - Temporal boundaries via composition with VideoTimeSegment pattern
    - Hierarchical chapters supported via parent_chapter_id
    - Schema.org Clip alignment for semantic web compatibility
    see_also:
    - https://support.google.com/youtube/answer/9884579
    - https://schema.org/Clip
    - https://www.w3.org/TR/media-frags/