구조화 데이터(JSON-LD) 적용 가이드

구조화 데이터란 무엇인가

구조화 데이터란 페이지에 이미 보이는 정보를 정해진 어휘로 다시 적어 둔 데이터입니다. 사람이 읽는 “2026년 9월 3일 발행, 글쓴이 홍길동”에 datePublished와 author라는 이름표를 붙이는 방식으로 이해할 수 있습니다. 이 가이드에서는 JSON 형태를 <script> 블록에 담는 JSON-LD를 사용합니다.

왜 JSON-LD를 쓰는가

Microdata나 RDFa는 HTML 요소마다 속성을 흩뿌리기 때문에 디자인을 바꾸면 데이터가 함께 깨집니다. JSON-LD는 독립된 script 블록 하나에 모여 있어 화면 코드와 분리되고, 문제가 생겼을 때 그 블록만 보면 됩니다.

잘못 쓰면 생기는 일

가장 흔한 실패는 조용한 실패입니다. JSON 문법 오류가 있으면 블록 전체가 무시되는데, 화면에는 아무 변화가 없어서 몇 달 동안 모르고 지나갑니다. 애드브랜치 검사기는 json-ld-valid-json으로 파싱 가능 여부를, json-ld-context와 json-ld-type으로 필수 키를 확인합니다.

더 위험한 것은 페이지 내용과 다른 값을 적는 경우입니다. 화면에 없는 별점을 마크업에만 넣거나, 실제와 다른 가격을 적는 것은 Google 구조화 데이터 정책 위반이며 수동 조치 대상이 될 수 있습니다. 마크업은 페이지에 실제로 있는 내용만 반영해야 합니다. 자세한 기준은 아래 “화면에 보이는 내용과 맞추기” 절에서 다룹니다.

기본 문법

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "sitemap.xml 만들기와 제출하기",
    "image": ["https://example.com/og/sitemap.png"],
    "datePublished": "2026-09-03T09:00:00+09:00",
    "dateModified": "2026-09-03T09:00:00+09:00",
    "author": {
      "@type": "Organization",
      "name": "예시 편집팀",
      "url": "https://example.com/about"
    }
  }
</script>

@context는 이 문서가 쓰는 어휘가 schema.org임을 선언하고, @type은 이 대상이 무엇인지 말합니다. @graph에서는 바깥 객체의 @context를 자식 노드와 함께 쓸 수 있습니다. JSON 문법, 페이지 내용과 타입의 일치, 제품별 기능 지원 여부는 서로 나눠 확인하세요.

현재 애드브랜치의 article-required-properties는 headline, image, 유효한 ISO 8601 datePublished가 없으면 critical로 표시하는 제품 규칙입니다. author나 dateModified가 없으면 warning입니다. 결과 카드도 이를 자체 점검 기준과 제품 우선순위로 설명하므로 Google의 색인·리치 결과 자격 판정으로 해석하면 안 됩니다.

자주 쓰는 타입

타입	쓰는 곳	핵심 속성
Article	블로그 글, 가이드, 뉴스	적용 가능한 headline, image, datePublished, author
Organization	회사·서비스 소개, 사이트 전역	name, url, logo
BreadcrumbList	계층 구조가 있는 하위 페이지	itemListElement의 position, name, item
WebSite	사이트 루트	name, url
WebPage	일반 페이지	name, url

Organization

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Organization",
    "name": "예제상점",
    "url": "https://example.com",
    "logo": "https://example.com/logo.png",
    "sameAs": ["https://www.linkedin.com/company/example", "https://github.com/example"]
  }
</script>

Google의 Organization 구조화 데이터 안내에는 필수 속성이 없습니다. 대신 url, logo(112x112px 이상), sameAs 같은 권장 속성을 실제 사실에 맞게 추가하고, 홈페이지나 회사 소개 페이지 한 곳에 두라고 설명합니다. sameAs에는 실제로 운영하는 공식 프로필 URL만 넣으세요. 없는 계정을 만들어 채울 필요는 없습니다.

애드브랜치 검사기는 두 항목으로 이 노드를 봅니다. organization-core-properties는 name과 url이 있는지, logo가 절대 URL인지 확인하는 제품 규칙이고, geo-c08-entity-sameas는 sameAs에 유효한 절대 URL이 있는지 보는 점수 없는 안내 항목입니다. 둘 다 Google의 필수 요건이 아니라 이 도구의 검토 신호입니다.

BreadcrumbList

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "BreadcrumbList",
    "itemListElement": [
      { "@type": "ListItem", "position": 1, "name": "홈", "item": "https://example.com/" },
      {
        "@type": "ListItem",
        "position": 2,
        "name": "가이드",
        "item": "https://example.com/guides"
      },
      {
        "@type": "ListItem",
        "position": 3,
        "name": "구조화 데이터",
        "item": "https://example.com/guides/structured-data"
      }
    ]
  }
</script>

position은 1부터 빠짐없이 이어져야 합니다. 애드브랜치의 breadcrumb-required-properties가 이 연속성을 확인합니다. 이 문서의 도메인, 조직명, 작성자, 이미지 URL은 모두 설명용 값이므로 실제 페이지에 보이는 사실로 바꾸세요.

@graph로 여러 엔티티 묶기

한 페이지에 여러 엔티티가 필요할 때는 @graph로 한 블록에 담고 @id로 서로를 참조하면 같은 조직 정보를 반복하지 않아도 됩니다. Google의 Organization 문서는 @id를 권장 속성으로 안내하지 않습니다. @id를 쓴다면 같은 엔티티에 같은 값을 유지하세요.

<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@graph": [
      {
        "@type": "Organization",
        "@id": "https://example.com/#org",
        "name": "예제상점",
        "url": "https://example.com",
        "logo": "https://example.com/logo.png"
      },
      {
        "@type": "WebSite",
        "@id": "https://example.com/#website",
        "url": "https://example.com",
        "name": "예제상점",
        "publisher": { "@id": "https://example.com/#org" }
      },
      {
        "@type": "Article",
        "headline": "구조화 데이터 적용 가이드",
        "image": ["https://example.com/og/sd.png"],
        "datePublished": "2026-09-03",
        "dateModified": "2026-09-03",
        "author": { "@id": "https://example.com/#org" },
        "publisher": { "@id": "https://example.com/#org" },
        "isPartOf": { "@id": "https://example.com/#website" }
      }
    ]
  }
</script>

잘못된 예와 수정된 예

1. JSON 문법이 깨진 블록

<!-- 잘못된 예: 후행 콤마, 홑따옴표, 이스케이프 안 된 따옴표 -->
<script type="application/ld+json">
  {
    '@context': 'https://schema.org',
    "@type": "Article",
    "headline": "제품 "베스트" 후기",
  }
</script>

JSON은 홑따옴표를 허용하지 않고, 마지막 속성 뒤 콤마도 오류이며, 값 안의 따옴표는 이스케이프해야 합니다. 이 블록은 통째로 무시됩니다.

<!-- 수정된 예 -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Article",
    "headline": "제품 \"베스트\" 후기",
    "image": ["https://example.com/og/review.png"],
    "datePublished": "2026-09-03"
  }
</script>

템플릿에서 값을 끼워 넣을 때는 문자열 연결 대신 언어에 내장된 JSON 직렬화 함수를 쓰세요.

2. 페이지에 없는 내용을 마크업

<!-- 잘못된 예: 화면 어디에도 리뷰와 별점이 없는 페이지 -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "노트북 거치대",
    "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.9", "reviewCount": "312" }
  }
</script>

사용자에게 보이지 않는 평점을 마크업에만 넣는 것은 정책 위반입니다.

<!-- 수정된 예: 실제 페이지에 있는 정보만 -->
<script type="application/ld+json">
  {
    "@context": "https://schema.org",
    "@type": "Product",
    "name": "노트북 거치대",
    "image": ["https://example.com/img/stand.png"],
    "brand": { "@type": "Brand", "name": "예제상점" }
  }
</script>

화면에 보이는 내용과 맞추기

Google 구조화 데이터 일반 지침은 독자에게 보이지 않는 내용을 마크업하지 말고, 구조화 데이터가 페이지 내용을 그대로 나타내야 한다고 정합니다. 이 지침을 어기면 구조화 데이터 수동 조치를 받을 수 있는데, 수동 조치 보고서 안내에 따르면 이 조치는 리치 결과 자격을 없앨 뿐 검색 순위에는 영향을 주지 않습니다. 보이지 않는 요소에 붙인 마크업은 이 보고서에 실제 조치 항목으로 올라 있습니다.

실무에서 자주 어긋나는 곳은 세 군데입니다.

• Article 계열의 headline이 화면의 H1이나 title과 다른 문장인 경우. 템플릿에서 옛 제목이 남아 있을 때 흔합니다.
• FAQPage의 질문과 답변이 화면 문답과 다르거나, 화면에서 지운 문답이 JSON-LD에만 남은 경우.
• 화면에 없는 평점, 가격, 재고 정보를 마크업에만 적은 경우.

애드브랜치 검사기의 json-ld-visible-match는 이 중 앞의 두 가지를 봅니다. FAQPage의 질문 name과 답변 text 앞부분, Article 계열의 headline을 실제 p 요소에서 모은 최대 20,000자의 본문 표본, H1, title과 비교합니다. 인라인 마크업은 같은 문단 텍스트로 유지합니다. 확인 가능한 항목이 2개 이상인데 모두 없으면 critical, 일부만 없으면 warning입니다. 본문 표본이 잘려 비교하지 못한 항목은 실패가 아니라 확인 불가로 남기고, 초기 HTML에 본문이 거의 없는 페이지는 판정하지 않습니다.

검증 방법

• JSON 파서: 문법 오류를 먼저 확인합니다.
• 페이지 화면: 마크업 값과 독자에게 보이는 내용을 직접 비교합니다.
• 애드브랜치 검사기: json-ld-present부터 breadcrumb-required-properties, json-ld-visible-match까지 초기 HTML만으로 판정 가능한 항목을 한 번에 확인합니다. 초기 HTML에서 확인하지 못한 항목은 실패가 아니라 “확인 불가”로 남깁니다.

적용 시 주의점과 흔한 오해

• 구조화 데이터를 넣으면 리치 결과가 보장된다고 오해하기 쉽습니다. 마크업은 자격 요건일 뿐이고 표시 여부는 검색엔진이 결정합니다.
• JSON이 깨졌다면 먼저 문법 오류를 고치세요. schema.org 문법이 맞아도 Google이 지원하는 리치 결과 유형이 아닐 수 있고, FAQ나 HowTo처럼 이미 중단된 유형도 있습니다. 권장 속성 경고가 사라져도 표시 여부는 별개입니다.
• 구조화 데이터를 순위나 노출을 보장하는 장치로 다루지 마세요. 화면 내용을 정확히 다시 표현하는 데 집중합니다.
• 타입을 억지로 늘리지 마세요. 회사 소개 페이지에 Article을 붙이는 식의 마크업은 내용과 어긋납니다.
• 사이트 전체에서 조직 이름을 한 가지로 통일하세요. title, 푸터, JSON-LD publisher.name이 제각각이면 C04(엔티티명 일관성)에서 걸립니다.
• JavaScript로 나중에 삽입하는 JSON-LD는 초기 HTML만 읽는 도구에 잡히지 않습니다. 가능하면 서버에서 렌더하세요.

자주 묻는 질문

구조화 데이터가 없으면 SEO에 불리한가요

애드브랜치 검사기는 JSON-LD가 없으면 치명적 오류가 아니라 참고 정보로 표시합니다. 페이지에 넣기로 했다면 화면 내용과 같은 사실만 적고, 제품 점수만을 위해 값을 만들어 넣지 마세요.

script 블록은 몇 개까지 넣을 수 있나요

여러 블록을 쓸지 @graph로 묶을지는 템플릿 구조에 맞게 정하세요. 같은 엔티티를 서로 다른 값으로 중복 선언하지 않도록 생성 결과를 확인합니다.

FAQPage 마크업을 넣으면 검색 결과에 FAQ가 표시되나요

표시되지 않습니다. Google 검색 문서 변경 이력은 2026년 5월 7일부터 FAQ 리치 결과를 Google 검색에서 더 이상 보여 주지 않는다고 안내하며, 관련 문서도 2026년 6월 15일에 삭제됐습니다. 정부나 의료 사이트에 적용되던 과거 예외도 최신 기준이 아닙니다. 그렇다고 FAQ 본문이나 기존 FAQPage 마크업을 반드시 지워야 하는 것은 아닙니다. Google은 2023년 리치 결과 변경 안내에서 쓰이지 않는 구조화 데이터가 검색에 문제를 일으키지는 않는다고 설명했습니다. 남겨 둔다면 화면 문답과 같은 내용인지만 확인하세요. json-ld-visible-match가 이 일치 여부를 봅니다.

JSON-LD를 head에 넣어야 하나요 body에 넣어야 하나요

초기 HTML에서 검사할 수 있는 위치에 두고 생성 결과를 확인하세요. 페이지마다 값이 달라야 하는 항목을 공통 레이아웃에 고정해 두지 마세요.

관련 가이드

• 제목 구조(H1~H6) 설계
• GEO 점검 체크리스트
• SEO 기본 점검 체크리스트