768 lines
22 KiB
YAML
768 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#
|
|
wd: 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_language:
|
|
description: Default/primary language of the video content
|
|
range: string
|
|
slot_uri: schema:inLanguage
|
|
|
|
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
|