id: https://nde.nl/ontology/hc/class/VideoChapter
name: video_chapter_class
title: Video Chapter Class
imports:
  - linkml:types
  - ../enums/ChapterSourceEnum
  - ../slots/has_description
  - ../slots/identified_by
  - ../slots/has_label
  - ../slots/has_hypernym
  - ../slots/has_score
  - ../slots/indexed_as
  - ../slots/has_source
  - ../slots/has_thumbnail
  - ../slots/created_through
  - ../slots/nested_in
  - ../slots/begin_of_the_begin
  - ../slots/end_of_the_end
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```\n\
      Corresponds 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:
    - created_through
    - has_description
    - identified_by
    - indexed_as
    - has_source
    - has_thumbnail
    - has_label
    - nested_in
    - has_hypernym
    - has_score
    - begin_of_the_begin
    - end_of_the_end
    - begin_of_the_begin
    - end_of_the_end
    slot_usage:
      identified_by:
#         range: string
        required: true
        examples:
        - value: ABC123_chapter_0
        - value: 550e8400-e29b-41d4-a716-446655440000
      has_label:
        range: Label
        inlined: true
        required: true
        examples:
        - value:
            has_label: De Nachtwacht (The Night Watch)
            language: nl
        - value:
            has_label: 'Curator Interview: Conservation Process'
            language: en
      indexed_as:
        range: integer
        required: true
        minimum_value: 0
        examples:
        - value: 0
        - value: 5
      has_description:
#         range: string
        required: false
        examples:
        - value: Dr. Dibbits discusses the restoration of Rembrandt's masterpiece,
            including the controversial 2019 operation.
      created_through:
        range: boolean
        required: false
        examples:
        - value: false
        - value: true
      has_source:
        range: ChapterSourceEnum
        required: false
        examples:
        - value: MANUAL
      has_thumbnail:
        range: Thumbnail
        inlined: true
        required: false
        examples:
        - value:
            has_url: https://i.ytimg.com/vi/ABC123/hq1.jpg
        - value:
            has_url: https://i.ytimg.com/vi/ABC123/hq1.jpg
            derive_from:
              has_url: https://www.youtube.com/watch?v=ABC123
            has_time_interval:
              duration_description: 'Frame at 2:02.5 (was chapter_thumbnail_timestamp:
                122.5)'
      has_hypernym:
#         range: string
        required: false
        examples:
        - value: ABC123_chapter_0
      nested_in:
        range: integer
        required: false
        minimum_value: 0
        examples:
        - value: 0
        - value: 1
    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/
    annotations:
      specificity_score: 0.1
      specificity_rationale: Generic utility class/slot created during migration
      custodian_types: '[''*'']'