구조·마크업 · 공식 문서
VideoObject 구조화된 데이터 필수 속성과 작성 순서
VideoObject 는 보기 페이지에 JSON-LD 로 넣고, 필수 속성 3개(name, thumbnailUrl, uploadDate)에 영상 파일 URL(contentUrl)이나 플레이어 URL(embedUrl)을 더합니다. 동영상 사이트맵도 쓰면 같은 정보를 짝이 되는 태그에 같은 값으로 적습니다.
영상 정보를 구글에 알리는 통로는 구조화된 데이터와 동영상 사이트맵입니다. 둘 중 무엇이 필요한지는 「동영상 사이트맵 필요한 경우와 구조화된 데이터 선택 기준」 편에 자세히 적었습니다.
이 편은 정한 다음의 일, 곧 VideoObject 를 실제로 쓰는 법과 사이트맵 태그로 옮기는 짝을 다룹니다.
발견 01
VideoObject 의 필수 속성은 3개이고, 빠지면 구글이 영상 정보를 읽지 못할 수 있습니다
You must include the required VideoObject properties for your markup to be eligible for usage in Google Search.
마크업이 구글 검색에 쓰이려면 VideoObject 필수 속성을 넣어야 합니다.
| 필수 속성 | 적는 값 | 공식 문서 원문 |
|---|---|---|
| name | 영상 제목. 사이트 안에서 영상마다 다르게 | The title of the video. Make sure to use unique text in the name property for each video on your site.영상 제목입니다. 사이트 안에서 영상마다 다른 name 을 씁니다. |
| thumbnailUrl | 영상마다 고유한 썸네일 이미지 URL | A URL pointing to the video's unique thumbnail image file. Follow the thumbnail image guidelines.영상의 고유한 썸네일 이미지 파일 URL입니다. 썸네일 지침을 따릅니다. |
| uploadDate | 처음 게시한 날짜와 시각. ISO 8601, 시간대 포함 | The date and time the video was first published, in ISO 8601 format. We recommend that you provide timezone information; otherwise, we will default to the timezone used by Googlebot.영상을 처음 게시한 날짜와 시각을 ISO 8601 형식으로 적습니다. 시간대를 적기를 권하며, 없으면 Googlebot 의 시간대로 봅니다. |
uploadDate 에는 시간대를 붙입니다. 한국 시간이면 +09:00 을 적어야 구글 크롤러의 시간대로 바뀌어 읽히는 일을 피합니다.
구조화된 데이터는 지침을 지켜야 쓰입니다(원문: For your video structured data to be eligible for usage in Google Search, you must follow the Search Essentials, general structured data guidelines, and video indexing requirements.) 동영상 색인 조건은 「구글 동영상 색인 조건」 편에 자세히 적었습니다.
| 속성 | 예시 값 |
|---|---|
| @context | https://schema.org |
| @type | VideoObject |
| name | 산업용 펌프 분해 정비 시연 |
| description | 현장에서 펌프 씰을 교체하는 순서를 단계별로 보여 주는 영상입니다. |
| thumbnailUrl | https://www.example.com/videos/pump-seal/thumb-16x9.jpg |
| uploadDate | 2026-10-20T09:00:00+09:00 |
| duration | PT2M30S |
| contentUrl | https://www.example.com/videos/pump-seal/file.mp4 |
발견 02
속성 9가지는 사이트맵 태그와 짝이 있고, 두 문서가 필수로 적은 항목은 서로 다릅니다
| VideoObject 속성 | 구조화된 데이터 | 사이트맵 태그 | 사이트맵 | 적는 값 | 공식 문서 원문 |
|---|---|---|---|---|---|
| name | 필수 | <video:title> | 필수 | 영상 제목. 사이트 안에서 영상마다 다르게 | The title of the video. Make sure to use unique text in the name property for each video on your site.영상 제목입니다. 사이트 안에서 영상마다 다른 name 을 씁니다. |
| thumbnailUrl | 필수 | <video:thumbnail_loc> | 필수 | 영상마다 고유한 썸네일 이미지 URL | A URL pointing to the video's unique thumbnail image file. Follow the thumbnail image guidelines.영상의 고유한 썸네일 이미지 파일 URL입니다. 썸네일 지침을 따릅니다. |
| uploadDate | 필수 | <video:publication_date> | 선택 | 처음 게시한 날짜와 시각. ISO 8601, 시간대 포함 | The date and time the video was first published, in ISO 8601 format. We recommend that you provide timezone information; otherwise, we will default to the timezone used by Googlebot.영상을 처음 게시한 날짜와 시각을 ISO 8601 형식으로 적습니다. 시간대를 적기를 권하며, 없으면 Googlebot 의 시간대로 봅니다. |
| description | 권장 | <video:description> | 필수 | 영상 설명. 영상마다 다르게 | The description of the video. Make sure to use unique text in the description property for each video on your site. HTML tags are ignored.영상 설명입니다. 영상마다 다른 description 을 쓰며, HTML 태그는 무시됩니다. |
| contentUrl | 권장 | <video:content_loc> | 필수 | 영상 파일 자체의 URL | This is the most effective way for Google to fetch your video content files. If contentUrl isn't available, provide embedUrl as an alternative.contentUrl 은 구글이 영상 파일을 가져가는 가장 효과적인 방법입니다. contentUrl 이 없으면 embedUrl 을 대신 적습니다. |
| embedUrl | 권장 | <video:player_loc> | 필수 | 플레이어 URL(대개 iframe 의 src 값) | Don't link to the page where the video lives; this must be the URL of the video player itself.영상이 있는 페이지 URL이 아니라 영상 플레이어 자체의 URL이어야 합니다. |
| duration | 권장 | <video:duration> | 선택 | 길이. 구조화된 데이터는 ISO 8601, 사이트맵은 초 단위 | For example, PT00H30M5S represents a duration of "thirty minutes and five seconds".예를 들어 PT00H30M5S 는 30분 5초를 뜻합니다. |
| expires | 권장 | <video:expiration_date> | 선택 | 내려갈 날짜. 만료가 없으면 적지 않음 | Don't supply this information if your video does not expire.영상에 만료가 없으면 이 정보를 적지 않습니다. |
| regionsAllowed 또는 ineligibleRegion | 권장 | <video:restriction> | 선택 | 허용·제외할 국가 코드 | Add either ineligibleRegion or regionsAllowed, whichever makes sense for your site.ineligibleRegion 이나 regionsAllowed 중 사이트에 맞는 하나를 넣습니다. |
사이트맵은 설명과 영상 URL을 필수로 두고, 구조화된 데이터는 게시일을 필수로 둡니다. 두 통로를 함께 쓰면 양쪽 필수를 모두 채웁니다(원문: It's required to provide either a <video:content_loc> or <video:player_loc> tag.)
사이트맵의 짝은 문서가 직접 적었습니다(원문: This is the equivalent of VideoObject.contentUrl in structured data. / This is the equivalent of VideoObject.embedUrl in structured data.) 사이트맵 설명은 최대 2048자입니다(원문: Maximum 2048 characters.)
발견 03
작성 순서는 7단계이고, 몇 페이지에 먼저 올려 URL 검사로 확인한 뒤 넓힙니다
| 순서 | 단계 | 하는 일 | 공식 문서 원문 |
|---|---|---|---|
| 1 | 보기 페이지 고르기 | 영상 하나가 주인공인 보기 페이지에 마크업을 넣습니다. | Adding video structured data to your watch pages can also make it easier for Google to find your video.보기 페이지에 동영상 구조화된 데이터를 넣으면 구글이 영상을 찾기도 쉬워집니다. |
| 2 | 필수 속성 | name, thumbnailUrl, uploadDate 를 넣습니다. 빠지면 영상 정보를 하나도 못 읽을 수 있습니다. | If you don't include the required properties, Google may not be able to extract any information about the video.필수 속성을 넣지 않으면 구글이 영상 정보를 하나도 뽑아내지 못할 수 있습니다. |
| 3 | 영상 URL | 영상 파일 URL을 contentUrl 로 넣고, 없으면 플레이어 URL을 embedUrl 로 넣습니다. | This is the most effective way for Google to fetch your video content files. If contentUrl isn't available, provide embedUrl as an alternative.contentUrl 은 구글이 영상 파일을 가져가는 가장 효과적인 방법입니다. contentUrl 이 없으면 embedUrl 을 대신 적습니다. |
| 4 | 권장 속성 | description, duration 을 더하고 만료·지역 제한이 있으면 그 속성도 넣습니다. | While Google tries to automatically understand details about your video, you can influence the information that's shown in video results, such as the description, thumbnail URL, upload date, and duration, by marking up your video with VideoObject.구글이 영상 정보를 자동으로 파악하려 하지만, VideoObject 로 표시하면 설명·썸네일 URL·게시일·길이처럼 동영상 결과에 보이는 정보에 영향을 줄 수 있습니다. |
| 5 | 사이트맵과 값 맞추기 | 동영상 사이트맵도 쓰면 썸네일 URL과 설명을 같은 값으로 둡니다. | If you choose to specify multiple metadata sources (for example, specifying a thumbnail in both your sitemap and structured data), make sure you're using the same thumbnail URL per video across all metadata.사이트맵과 구조화된 데이터처럼 여러 곳에 영상 정보를 적으면, 영상마다 같은 썸네일 URL을 씁니다. |
| 6 | 리치 결과 테스트 | 코드를 리치 결과 테스트에 넣고 심각한 오류를 고칩니다. | Validate your code using the Rich Results Test and fix any critical errors.리치 결과 테스트로 코드를 검사하고 심각한 오류를 고칩니다. |
| 7 | 몇 페이지 먼저 배포 | 몇 페이지에만 먼저 올리고 URL 검사로 구글이 보는 페이지를 확인합니다. | Deploy a few pages that include your structured data and use the URL Inspection tool to test how Google sees the page.구조화된 데이터를 넣은 페이지 몇 개를 먼저 배포하고 URL 검사 도구로 구글이 페이지를 어떻게 보는지 확인합니다. |
같은 영상을 여러 페이지에 넣었다면 마크업은 보기 페이지에 둡니다. 동영상 결과의 대상이 보기 페이지이기 때문입니다.
리치 결과 테스트의 오류 읽는 법은 「리치 결과 테스트 오류와 경고 읽는 법, 고치는 순서」 편에 자세히 적었습니다.
발견 04
같은 속성이라도 B2B·B2C·B2G 는 채울 값의 출처가 다릅니다
예시 ① 시연 영상을 자체 서버에 둔 장비 제조사(B2B)
영상 파일이 회사 서버에 있으므로 contentUrl 에 파일 URL을 적습니다. 위 예시 값이 이 경우입니다.
제품 페이지 틀에서 영상 제목과 설명을 끌어오면, 영상마다 다른 name 과 description 이 자동으로 채워집니다.
예시 ② 유튜브 영상을 임베드한 쇼핑몰 브랜드 페이지(B2C)
영상 파일 URL이 없으므로 embedUrl 에 유튜브 플레이어 URL을 적습니다. 썸네일은 고정된 URL의 이미지를 따로 지정합니다.
기획전이 끝나 영상을 내릴 날짜가 정해져 있으면 expires 를 적습니다. 사이트맵도 쓰면 <video:expiration_date> 에 같은 날짜를 적습니다.
예시 ③ 국내에서만 공개하는 교육 영상을 둔 공공기관 누리집(B2G)
교육 영상의 이용 범위가 국내로 정해져 있습니다. regionsAllowed 에 KR 을 적어 허용 국가를 알립니다.
게시일은 누리집 게시판의 등록 시각을 시간대와 함께 uploadDate 에 넣습니다.
그럼 첫 영상 페이지에는 어떤 순서로 넣나요?
- 영상 하나가 주인공인 보기 페이지 하나를 고릅니다.
- 필수 속성 3개와 contentUrl 또는 embedUrl 을 JSON-LD 로 씁니다.
- description 과 duration 을 더하고, 만료·지역 제한이 있으면 그 속성도 씁니다.
- 리치 결과 테스트로 검사하고, URL 검사로 구글이 보는 페이지를 확인합니다.
- 틀에 넣어 나머지 보기 페이지로 넓히고, 사이트맵도 쓰면 같은 값을 태그에 적습니다.
조사 방법
- Google Search Central 「Video (VideoObject, Clip, BroadcastEvent) structured data」 (문서 수정일 2026-09-24) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/video
- Google Search Central 「Video sitemaps and alternatives」 (문서 수정일 2026-05-20) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/crawling-indexing/sitemaps/video-sitemaps
- Google Search Central 「Video SEO best practices」 (문서 수정일 2025-12-18) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/video
- 속성 9가지와 작성 순서 7단계는 위 문서의 문장을 묶어 정리한 것입니다. 묶는 방식은 편집 판단입니다.
- 예시 값과 예시 ①②③은 이해를 돕기 위해 만든 가상 상황이며, 실제 기업·기관의 사례가 아닙니다.
- 원문은 영어판(hl=en)이고, 도구·보고서 이름은 같은 문서 한국어판(hl=ko) 표기를 따랐습니다.