glam/schemas/20251121/linkml/modules/classes/VideoPost.yaml
kempersc 51554947a0 feat(schema): Add video content schema with comprehensive examples
Video Schema Classes (9 files):
- VideoPost, VideoComment: Social media video modeling
- VideoTextContent: Base class for text content extraction
- VideoTranscript, VideoSubtitle: Text with timing and formatting
- VideoTimeSegment: Time code handling with ISO 8601 duration
- VideoAnnotation: Base annotation with W3C Web Annotation alignment
- VideoAnnotationTypes: Scene, Object, OCR detection annotations
- VideoChapter, VideoChapterList: Navigation and chapter structure
- VideoAudioAnnotation: Speaker diarization, music, sound events

Enumerations (12 enums):
- VideoDefinitionEnum, LiveBroadcastStatusEnum
- TranscriptFormatEnum, SubtitleFormatEnum, SubtitlePositionEnum
- AnnotationTypeEnum, AnnotationMotivationEnum
- DetectionLevelEnum, SceneTypeEnum, TransitionTypeEnum, TextTypeEnum
- ChapterSourceEnum, AudioEventTypeEnum, SoundEventTypeEnum, MusicTypeEnum

Examples (904 lines, 10 comprehensive heritage-themed examples):
- Rijksmuseum virtual tour chapters (5 chapters with heritage entity refs)
- Operation Night Watch documentary chapters (5 chapters)
- VideoAudioAnnotation: curator interview, exhibition promo, museum lecture

All examples reference real heritage entities with Wikidata IDs:
Q5598 (Rembrandt), Q41264 (Vermeer), Q219831 (The Night Watch)
2025-12-16 20:03:17 +01:00

763 lines
22 KiB
YAML

# Video Post Class
# Concrete subclass of SocialMediaPost for video content with platform-specific properties
#
# Part of Heritage Custodian Ontology v0.9.5
#
# STRUCTURE:
# SocialMediaPost (parent)
# └── VideoPost (this class)
# - duration, definition, captions
# - view/like/comment metrics
# - YouTube-specific fields
#
# DATA SOURCE EXAMPLE:
# From data/custodian/NL-GE-AAL-M-NOM-nationaal_onderduikmuseum.yaml:
# youtube_enrichment:
# videos:
# - video_id: FbIoC-Owy-M
# duration: PT10M59S
# definition: hd
# caption_available: false
# view_count: 132
# like_count: 2
# comment_count: 0
id: https://nde.nl/ontology/hc/class/VideoPost
name: video_post_class
title: Video Post Class
imports:
- linkml:types
- ./SocialMediaPost
- ./SocialMediaPostTypes
- ../slots/language
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/
skos: http://www.w3.org/2004/02/skos/core#
as: https://www.w3.org/ns/activitystreams#
wikidata: http://www.wikidata.org/entity/
default_prefix: hc
classes:
VideoPost:
is_a: SocialMediaPost
class_uri: as:Video
abstract: false
description: |
Concrete class for video content with platform-specific properties.
**DEFINITION**:
VideoPost is a specialized SocialMediaPost for video content. It extends
the base post class with video-specific slots for duration, resolution,
captions, and engagement metrics.
**EXTENDS**: SocialMediaPost
This class adds:
- Video technical properties (duration, definition, aspect ratio)
- Caption and subtitle availability
- Engagement metrics (views, likes, comments)
- Platform-specific fields (YouTube category, live broadcast status)
- Temporal markers (chapters, segments)
**ONTOLOGY MAPPINGS**:
| Property | Activity Streams | Schema.org |
|----------|------------------|------------|
| Class | as:Video | schema:VideoObject |
| duration | as:duration | schema:duration |
| definition | - | schema:videoQuality |
| caption | - | schema:caption |
| view_count | - | schema:interactionStatistic |
**PLATFORM SUPPORT**:
| Platform | Duration Limit | Resolution | Captions |
|----------|----------------|------------|----------|
| YouTube | 12 hours (verified) | Up to 8K | VTT, SRT |
| Vimeo | Varies by plan | Up to 8K | VTT, SRT |
| Facebook | 4 hours | Up to 4K | Auto-generated |
| TikTok | 10 minutes | 1080p | Auto-generated |
| Instagram Reels | 90 seconds | 1080p | Auto-generated |
**HERITAGE INSTITUTION USE CASES**:
| Content Type | Typical Duration | Platform |
|--------------|------------------|----------|
| Virtual tours | 10-30 min | YouTube |
| Conservation docs | 5-20 min | YouTube, Vimeo |
| Curator interviews | 15-60 min | YouTube |
| Object spotlights | 2-5 min | YouTube, Instagram |
| Short clips | 15-60 sec | TikTok, Reels |
| Live recordings | 30-120 min | YouTube |
**METRICS OBSERVATION**:
Video metrics (views, likes, comments) are observational data that change
constantly. Each metric reading should include:
- `metrics_observed_at`: When metrics were recorded
- `retrieval_timestamp`: When API call was made
**RELATIONSHIP TO VideoPostType**:
- VideoPost is a **concrete post instance** with video content
- VideoPostType is a **type classification** for categorizing posts
- A VideoPost typically has `post_types: [VideoPostType]`
- But may also have multiple types: `[LiveStreamPostType, VideoPostType]`
**CAPTION AND SUBTITLE DISTINCTION**:
Related classes for textual content derived from video:
- VideoSubtitle: Time-coded text (SRT/VTT format)
- VideoTranscript: Full text without timestamps
- VideoAnnotation: Computer vision derived content
See VideoTextContent hierarchy for detailed modeling.
exact_mappings:
- as:Video
- schema:VideoObject
close_mappings:
- crm:E73_Information_Object
related_mappings:
- wikidata:Q34508 # Video
- wikidata:Q604644 # Online video
slots:
# ========================================
# Video Technical Properties
# ========================================
- duration
- definition
- aspect_ratio
- frame_rate
# ========================================
# Caption and Subtitle Availability
# ========================================
- caption_available
- default_language
- default_audio_language
- available_caption_languages
# ========================================
# Engagement Metrics
# ========================================
- view_count
- like_count
- dislike_count
- comment_count
- favorite_count
- metrics_observed_at
# ========================================
# Platform-Specific
# ========================================
- video_category_id
- live_broadcast_content
- is_licensed_content
- is_embeddable
- is_made_for_kids
# ========================================
# Comments/Replies
# ========================================
- comments_fetched
- video_comments
slot_usage:
# --- Video Technical Properties ---
duration:
slot_uri: schema:duration
description: |
Duration of the video in ISO 8601 format.
Schema.org: duration for media length.
**Format**: ISO 8601 duration (e.g., "PT10M59S" = 10 minutes 59 seconds)
**Common Patterns**:
- PT30S = 30 seconds
- PT5M = 5 minutes
- PT1H30M = 1 hour 30 minutes
- PT2H15M30S = 2 hours 15 minutes 30 seconds
range: string
required: false
pattern: "^P(T(\\d+H)?(\\d+M)?(\\d+S)?)?$"
examples:
- value: "PT10M59S"
description: "10 minutes and 59 seconds"
- value: "PT1H30M"
description: "1 hour 30 minutes"
definition:
slot_uri: schema:videoQuality
description: |
Video resolution/definition quality.
Schema.org: videoQuality for resolution class.
**Values**:
- sd: Standard definition (480p or lower)
- hd: High definition (720p, 1080p)
- 4k: Ultra HD (2160p)
- 8k: Full Ultra HD (4320p)
range: VideoDefinitionEnum
required: false
examples:
- value: "hd"
description: "High definition (720p/1080p)"
aspect_ratio:
slot_uri: schema:width
description: |
Video aspect ratio.
**Common Values**:
- 16:9: Standard widescreen (YouTube default)
- 9:16: Vertical (Shorts, Reels, TikTok)
- 4:3: Classic TV format
- 1:1: Square (Instagram legacy)
- 21:9: Cinematic ultrawide
range: string
required: false
examples:
- value: "16:9"
description: "Standard widescreen"
- value: "9:16"
description: "Vertical format for Shorts/Reels"
frame_rate:
slot_uri: hc:frameRate
description: |
Video frame rate in frames per second.
**Common Values**:
- 24: Cinema standard
- 25: PAL standard
- 30: NTSC standard
- 60: High frame rate
range: float
required: false
examples:
- value: 30.0
description: "30 frames per second"
# --- Caption and Subtitle Availability ---
caption_available:
slot_uri: schema:hasPart
description: |
Whether captions/subtitles are available for this video.
Indicates if the video has any caption tracks (auto-generated or manual).
Related: Use `available_caption_languages` for specific languages.
range: boolean
required: false
examples:
- value: true
description: "Video has captions available"
- value: false
description: "No captions available"
default_language:
slot_uri: schema:inLanguage
description: |
Default/primary language of the video content.
Schema.org: inLanguage for content language.
ISO 639-1 code (e.g., "nl", "en", "de").
Refers to on-screen text, title, description language.
range: string
required: false
examples:
- value: "nl"
description: "Dutch language content"
default_audio_language:
slot_uri: hc:defaultAudioLanguage
description: |
Language of the video's default audio track.
ISO 639-1 code. May differ from `default_language` for
dubbed or multilingual content.
range: string
required: false
examples:
- value: "nl"
description: "Dutch audio track"
available_caption_languages:
slot_uri: hc:availableCaptionLanguages
description: |
List of languages for which captions are available.
ISO 639-1 codes for all caption tracks.
range: string
multivalued: true
required: false
examples:
- value: ["nl", "en", "de"]
description: "Captions available in Dutch, English, German"
# --- Engagement Metrics ---
view_count:
slot_uri: schema:interactionCount
description: |
Number of views for this video.
Schema.org: interactionCount for view statistic.
**OBSERVATIONAL**: This value changes constantly.
Always record `metrics_observed_at` timestamp.
range: integer
required: false
minimum_value: 0
examples:
- value: 132
description: "132 views at observation time"
like_count:
slot_uri: hc:likeCount
description: |
Number of likes/upvotes for this video.
Platform-specific: YouTube likes, Facebook reactions, etc.
**OBSERVATIONAL**: Record with `metrics_observed_at`.
range: integer
required: false
minimum_value: 0
examples:
- value: 2
description: "2 likes at observation time"
dislike_count:
slot_uri: hc:dislikeCount
description: |
Number of dislikes/downvotes (if available).
Note: YouTube hid public dislike counts in Nov 2021.
API may still return dislike data for channel owners.
range: integer
required: false
minimum_value: 0
comment_count:
slot_uri: hc:commentCount
description: |
Number of comments on this video.
**OBSERVATIONAL**: Record with `metrics_observed_at`.
range: integer
required: false
minimum_value: 0
examples:
- value: 0
description: "No comments at observation time"
favorite_count:
slot_uri: hc:favoriteCount
description: |
Number of times video was favorited/saved.
Platform-specific availability.
range: integer
required: false
minimum_value: 0
metrics_observed_at:
slot_uri: prov:atTime
description: |
Timestamp when engagement metrics were recorded.
PROV-O: atTime for observation timestamp.
**CRITICAL**: Metrics change constantly. This timestamp
indicates when view_count, like_count, etc. were observed.
range: datetime
required: false
examples:
- value: "2025-12-01T23:16:22.294232+00:00"
description: "Metrics observed December 1, 2025"
# --- Platform-Specific ---
video_category_id:
slot_uri: hc:videoCategoryId
description: |
Platform-specific category identifier.
**YouTube Category IDs**:
- 1: Film & Animation
- 2: Autos & Vehicles
- 10: Music
- 15: Pets & Animals
- 17: Sports
- 19: Travel & Events
- 20: Gaming
- 22: People & Blogs
- 23: Comedy
- 24: Entertainment
- 25: News & Politics
- 26: Howto & Style
- 27: Education
- 28: Science & Technology
- 29: Nonprofits & Activism
range: string
required: false
examples:
- value: "22"
description: "YouTube: People & Blogs"
- value: "27"
description: "YouTube: Education"
live_broadcast_content:
slot_uri: hc:liveBroadcastContent
description: |
Live broadcast status of the video.
**Values**:
- none: Not a live broadcast (standard video)
- live: Currently broadcasting live
- upcoming: Scheduled live stream not yet started
When `live` or `upcoming` becomes `none`, video is archived.
range: LiveBroadcastStatusEnum
required: false
examples:
- value: "none"
description: "Standard video (not live)"
- value: "live"
description: "Currently broadcasting"
is_licensed_content:
slot_uri: hc:isLicensedContent
description: |
Whether the video contains licensed content (music, clips).
Affects monetization and regional availability.
range: boolean
required: false
is_embeddable:
slot_uri: hc:isEmbeddable
description: |
Whether the video can be embedded on external sites.
Publisher-controlled setting.
range: boolean
required: false
is_made_for_kids:
slot_uri: hc:isMadeForKids
description: |
Whether the video is designated as made for children.
COPPA compliance flag. Affects comments, ads, features.
range: boolean
required: false
# --- Comments ---
comments_fetched:
slot_uri: hc:commentsFetched
description: |
Number of comments actually fetched/archived.
May be less than `comment_count` due to API limits,
deleted comments, or pagination.
range: integer
required: false
minimum_value: 0
examples:
- value: 0
description: "No comments fetched"
video_comments:
slot_uri: hc:videoComments
description: |
Collection of comments on this video.
Structured comment data with author, text, timestamp, likes.
Note: Comments may contain nested replies.
range: VideoComment
multivalued: true
required: false
inlined: true
comments:
- "Extends SocialMediaPost with video-specific properties"
- "Maps to as:Video and schema:VideoObject"
- "Metrics are observational - always include metrics_observed_at"
- "Caption availability signals but not content (see VideoSubtitle)"
- "YouTube is primary platform for heritage institution video content"
see_also:
- "https://www.w3.org/ns/activitystreams#Video"
- "https://schema.org/VideoObject"
- "https://developers.google.com/youtube/v3/docs/videos"
# ==========================================================================
# Supporting Class: VideoComment
# ==========================================================================
VideoComment:
class_uri: schema:Comment
description: |
A comment on a video post.
Models user-generated comments with author, text, timestamp,
and engagement metrics. Supports nested reply threads.
exact_mappings:
- schema:Comment
- as:Note
slots:
- comment_id
- comment_author
- comment_author_channel_id
- comment_text
- comment_published_at
- comment_updated_at
- comment_like_count
- comment_reply_count
- comment_replies
slot_usage:
comment_id:
slot_uri: dcterms:identifier
description: Unique identifier for the comment
range: string
required: true
comment_author:
slot_uri: schema:author
description: Display name of comment author
range: string
required: true
comment_author_channel_id:
slot_uri: hc:authorChannelId
description: Platform channel/account ID of author
range: string
required: false
comment_text:
slot_uri: schema:text
description: Full text content of the comment
range: string
required: true
comment_published_at:
slot_uri: dcterms:created
description: When comment was originally posted
range: datetime
required: true
comment_updated_at:
slot_uri: dcterms:modified
description: When comment was last edited
range: datetime
required: false
comment_like_count:
slot_uri: hc:likeCount
description: Number of likes on this comment
range: integer
required: false
minimum_value: 0
comment_reply_count:
slot_uri: hc:replyCount
description: Number of replies to this comment
range: integer
required: false
minimum_value: 0
comment_replies:
slot_uri: schema:comment
description: Nested reply comments
range: VideoComment
multivalued: true
required: false
inlined: true
# ============================================================================
# Supporting Enumerations
# ============================================================================
enums:
VideoDefinitionEnum:
description: |
Video resolution/definition quality categories.
Based on common platform standards.
permissible_values:
sd:
description: Standard definition (480p or lower)
hd:
description: High definition (720p, 1080p)
uhd:
description: Ultra HD (2160p/4K)
4k:
description: 4K resolution (2160p) - alias for uhd
8k:
description: Full Ultra HD (4320p)
LiveBroadcastStatusEnum:
description: |
Live broadcast status values for video content.
Based on YouTube API liveBroadcastContent values.
permissible_values:
none:
description: Not a live broadcast (standard uploaded video)
live:
description: Currently broadcasting live
upcoming:
description: Scheduled live stream that hasn't started yet
# ============================================================================
# Slot Definitions
# ============================================================================
slots:
duration:
description: Duration in ISO 8601 format
range: string
definition:
description: Video resolution quality (sd, hd, 4k, 8k)
range: VideoDefinitionEnum
aspect_ratio:
description: Video aspect ratio (16:9, 9:16, 4:3, etc.)
range: string
frame_rate:
description: Frame rate in FPS
range: float
caption_available:
description: Whether captions are available
range: boolean
default_audio_language:
description: Language of default audio track
range: string
available_caption_languages:
description: Languages for which captions exist
range: string
multivalued: true
view_count:
description: Number of views
range: integer
like_count:
description: Number of likes
range: integer
dislike_count:
description: Number of dislikes
range: integer
comment_count:
description: Number of comments
range: integer
favorite_count:
description: Number of favorites/saves
range: integer
metrics_observed_at:
description: When metrics were recorded
range: datetime
video_category_id:
description: Platform category identifier
range: string
live_broadcast_content:
description: Live broadcast status
range: LiveBroadcastStatusEnum
is_licensed_content:
description: Contains licensed content
range: boolean
is_embeddable:
description: Can be embedded externally
range: boolean
is_made_for_kids:
description: COPPA kids content flag
range: boolean
comments_fetched:
description: Number of comments actually retrieved
range: integer
video_comments:
description: Collection of video comments
range: VideoComment
multivalued: true
# VideoComment slots
comment_id:
description: Unique comment identifier
range: string
comment_author:
description: Comment author display name
range: string
comment_author_channel_id:
description: Author's channel/account ID
range: string
comment_text:
description: Comment text content
range: string
comment_published_at:
description: When comment was posted
range: datetime
comment_updated_at:
description: When comment was edited
range: datetime
comment_like_count:
description: Likes on this comment
range: integer
comment_reply_count:
description: Number of replies
range: integer
comment_replies:
description: Nested reply comments
range: VideoComment
multivalued: true