# Structured Data Kr

> 웹페이지에 구조화 데이터(스키마 마크업)를 붙이거나 고칠 때 사용한다. 사용자가 '스키마 마크업', '구조화 데이터', 'JSON-LD', '리치 결과', '별점 노출', 'FAQ 스키마', '검색 결과에 정보 나오게'라고 말하면 이 스킬을 쓴다. 문법은 국제 표준이지만 예제의 주소·전화·통화를 한국 형식으로 바꿔야 하고, 네이버는 검증 경로와 지원 타입이 다르다. 검색 진단 전반은 google-search-kr, 네이버 노출은 naver-search-kr, AI 인용은 ai-answer-kr 을 쓴다.

- Skill: `svy04/structured-data-kr` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add svy04/structured-data-kr`
- Raw SKILL.md: https://api.skillmd.com/api/skills/svy04/structured-data-kr/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: svy04 (https://skillmd.com/u/svy04)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/svy04/structured-data-kr

---


# 구조화 데이터

당신은 마크업을 붙여 본 실무자다. 문법은 국제 표준이라 그대로 쓰되, **한국 사이트에서 달라지는 것**을 함께 다룬다.

`.agents/marketing-kr.md` 가 있으면 먼저 읽는다.

## 원칙 넷

1. **JSON-LD로 쓴다.** HTML에 섞지 않고 `<script type="application/ld+json">` 블록으로 둔다. 관리가 쉽다
2. **페이지에 없는 것을 마크업하지 않는다.** 화면에 안 보이는 별점·가격·FAQ를 마크업에만 넣는 것은 위반이다
3. **마크업이 노출을 보장하지 않는다.** 네이버도 구글도 이 점을 명시한다. "붙이면 별점이 나온다"고 말하지 않는다
4. **한 페이지의 여러 타입은 묶어서 쓴다.** 조각으로 흩어 놓지 않는다

## 한국 사이트에서 바꿔야 할 것

미국판 예제를 그대로 복사하면 아래가 틀린 채로 들어간다.

| 항목 | 미국판 예제 | 한국 |
|---|---|---|
| 주소 | 주(州)·우편번호 5자리·국가 코드 US | 시·도, 우편번호 5자리, 국가 코드 **KR** |
| 전화 | `+1-555-...` | `+82-2-...` 형식 (국가번호 82, 앞의 0을 뺀다) |
| 통화 | `USD` | **`KRW`** |
| 가격대 표기 | `$$` | 원화 기준으로 다시 정한다 |
| 영업시간 | 미국 시간대 | 한국 시간대 |

**통화 코드를 안 바꾸고 그대로 두는 실수가 가장 흔하다.** 가격 마크업을 붙일 때 반드시 확인한다.

## 어떤 타입을 쓰나

페이지 성격에 맞는 것을 고른다.

| 페이지 | 타입 |
|---|---|
| 회사 소개 | Organization (연관 채널을 함께 적을 수 있다) |
| 지역 업체 | LocalBusiness + 주소 |
| 상품 | Product + 가격·재고 |
| 후기·평점 | Review · AggregateRating (**화면에 실제로 있어야 한다**) |
| 자주 묻는 질문 | FAQPage (**구글은 리치 결과로 지원하지 않는다** — 아래) |
| 방법 안내 | HowTo (**구글은 리치 결과로 지원하지 않는다** — 아래) |
| 조리법 | Recipe |
| 영상 | VideoObject |
| 채용 공고 | JobPosting |
| 이동 경로 표시 | BreadcrumbList |
| 목록·캐러셀 | ItemList · ListItem |

### 구글이 더는 리치 결과로 보여 주지 않는 두 타입

`FAQPage` 와 `HowTo` 는 schema.org 어휘로는 그대로 살아 있다. 문법이 틀린 것이 아니다. 다만 **구글 검색이 둘 다 리치 결과로 보여 주지 않는다.** 구글 검색 센터의 구조화 데이터 갤러리 현행 목록에 둘 다 없다 (2026-08-22 확인).

- **HowTo** — 구글은 2023년 8월에 중단을 알렸고, 2023년 9월 14일 자 변경 기록에 "이 리치 결과가 데스크톱·모바일 양쪽 검색 결과에 더 이상 나오지 않으므로 How-to 구조화 데이터 문서를 삭제했다"고 적었다
- **FAQPage** — 2026년 5월 8일 자 변경 기록에 "2026년 5월 7일부터 이 기능이 구글 검색에 더 이상 나오지 않는다"고 적혔고, 2026년 6월 15일 자로 관련 문서가 삭제됐다

그래서 이렇게 다룬다.

- **이미 붙어 있으면 굳이 걷어내지 않는다.** 쓰이지 않는 마크업이 검색에 문제를 일으키지는 않는다고 구글이 밝혔다. 다만 구글 검색에서 눈에 보이는 효과도 없다
- **"FAQ 스키마를 붙이면 검색 결과에 질문이 펼쳐진다"고 말하지 않는다.** 지금은 그렇게 되지 않는다
- **`QAPage` 로 바꿔 넣지 않는다.** 구글은 `QAPage` 를 이용자가 답을 올릴 수 있는 페이지에만 쓰라고 하고, 사이트가 직접 쓴 FAQ 페이지에 쓰는 것을 명시적으로 금지한다 (2026-08-22 확인). 이름이 비슷하다고 대체물이 되지 않는다
- 구글 외의 검색 엔진이나 AI 서비스가 이 두 타입을 어떻게 쓰는지는 **확인하지 못했다**

FAQ 내용 자체를 지우라는 말이 아니다. 이용자에게 필요한 문답이면 **페이지에 그대로 두고**, 다만 검색 결과의 생김새를 그것으로 약속하지 않는다.

### 네이버 쪽

네이버도 구조화 데이터 가이드를 제공하며 위 타입들에 대한 안내가 있다. JSON-LD 또는 마이크로데이터를 권한다.

다만 두 가지를 분명히 한다.

- **마크업이 그 형식으로 노출되는 것을 보장하지 않는다** (네이버가 명시한다)
- 지역 업체 정보는 마크업보다 **스마트플레이스 정보가 본체**에 가깝다. 마크업으로 플레이스 정보를 대신할 수 없다

## 붙이는 순서

1. 페이지에 **실제로 있는** 정보를 목록으로 적는다
2. 그에 맞는 타입을 고른다
3. 필수 항목을 채운다. 선택 항목은 아는 것만
4. **검증한다** — 구글 리치 결과 테스트와 스키마 검증 도구
5. 배포한다
6. 며칠 뒤 검색 결과에서 실제로 어떻게 보이는지 확인한다

## 자주 나는 오류

- 화면에 없는 별점·리뷰를 마크업에만 넣음
- 통화 코드를 `USD` 로 둠
- 가격을 문자열로 넣고 숫자 형식을 안 맞춤
- 날짜 형식이 맞지 않음 (연-월-일 형식으로)
- 같은 페이지에 같은 타입을 여러 번 중복
- 마크업의 내용과 화면의 내용이 다름
- 이미지 URL이 상대 경로

## 구현 방법

- **정적 페이지**: 페이지 안에 JSON-LD 블록을 넣는다
- **동적 페이지**: 템플릿에서 데이터로 채운다. 값이 비면 그 항목을 아예 빼도록 처리한다 (빈 값이 들어가면 오류가 난다)
- **CMS·쇼핑몰 솔루션**: 대개 기본 마크업을 넣어 준다. **먼저 무엇이 이미 들어 있는지 확인한다.** 중복해서 넣으면 충돌한다

## AI 답변과의 관계

구조화 데이터는 기계가 읽기 좋게 만드는 일이므로 AI 인용에도 도움이 될 수 있다. 다만 **마크업만으로 인용되지는 않는다.** 본문이 잘라 쓸 수 있는 형태여야 한다 (`ai-answer-kr`).

## 하지 말 것

- 화면에 없는 정보를 마크업하지 않는다
- 통화·주소·전화 형식을 미국 예제 그대로 두지 않는다
- "마크업하면 별점이 나온다"고 말하지 않는다
- 스마트플레이스 정보를 마크업으로 대신하려 하지 않는다
- 검증 없이 배포하지 않는다
- 이미 솔루션이 넣어 준 마크업 위에 중복해 넣지 않는다
- FAQPage·HowTo 를 구글 리치 결과가 되는 것처럼 말하지 않는다
- 사이트가 직접 쓴 FAQ 페이지에 QAPage 를 대신 넣지 않는다

## 관련 스킬

- **google-search-kr**: 사이트 전반 진단
- **naver-search-kr**: 네이버 노출 (마크업과 별개 층이다)
- **ai-answer-kr**: AI 답변 인용
- **commerce-kr**: 상품 페이지의 필수 표시 항목

## 확인 시점과 한계

본문은 2026-08-22 기준이다. schema.org 어휘 자체는 국제 표준이라 안정적이지만, **검색 엔진이 어떤 타입을 어떻게 화면에 반영하는지는 자주 바뀐다.** 이 스킬의 표는 그 예다.

**이 시점에 원문에서 확인한 것**: 구글 검색 센터의 구조화 데이터 갤러리 현행 목록에 `FAQPage` 와 `HowTo` 가 없다. 구글 검색 센터 변경 기록에 HowTo 문서 삭제(2023-09-14)와 FAQ 기능 중단(2026-05-07 중단 고지, 2026-06-15 문서 삭제)이 적혀 있다. `QAPage` 는 갤러리에 남아 있으나 구글이 이용자 제출 답변이 있는 페이지로 용도를 한정한다. schema.org 에는 `FAQPage` 와 `HowTo` 가 폐기 표시 없이 그대로 정의돼 있다.

**확인하지 못한 것**: 네이버가 실제로 리치 결과로 노출하는 타입의 현행 목록, 구글 외 검색 엔진과 AI 서비스가 FAQPage·HowTo 를 쓰는지 여부, 한국 웹의 구조화 데이터 보급률.

**이전 판의 오류**: 이 스킬의 이전 판은 `FAQPage` 와 `HowTo` 를 아무 단서 없이 권했다. 구글 현행 목록을 확인해 단서를 붙였다.