JSON-LD 구조화 데이터란 — 넣는 위치와 필수 속성
블로그나 상품 페이지에 "JSON-LD를 넣으라"는 말은 들었는데, 그게 정확히 무엇이고 어디에 넣는 건지 막막한 분을 위한 글입니다.
결론부터 말하면 JSON-LD는 페이지의 내용을 검색엔진이 읽을 수 있는 형식으로 따로 적어 둔 데이터이고, HTML 안의 <script type="application/ld+json"> 태그에 넣습니다.
먼저 한 가지를 못 박아 두겠습니다. 마크업을 넣었다고 별점·이미지 같은 리치 결과가 나타나는 것은 아닙니다. 구글 문서가 "올바르게 마크업했더라도 검색 결과에 표시되는 것을 보장하지 않는다"고 직접 적어 두었습니다.
요약 ① JSON-LD는
<script type="application/ld+json">안에 넣는 JSON 데이터이며, 구글 문서 기준으로<head>와<body>어느 쪽에 넣어도 됩니다. ② 리치 결과 자격에는 유형별 필수 속성이 있습니다. Article은 필수 속성이 없고, 지역 비즈니스는 name과 address가 필수입니다. ③ 필수 속성을 다 채워도 노출은 보장되지 않습니다. FAQ 리치 결과처럼 기능 자체가 사라지기도 합니다.
구조화 데이터는 순위가 아니라 "표시"에 관여합니다
검색 결과에 별점, 가격, 이미지, 사이트 이름 같은 부가 요소가 붙은 결과를 리치 결과(rich result)라고 부릅니다. 이런 요소는 페이지 본문을 읽어서 추측한 값이 아니라, 페이지가 스스로 신고한 데이터에서 옵니다.
그 신고서가 구조화 데이터이고, 신고서를 쓰는 문법 중 하나가 JSON-LD입니다. 어휘는 schema.org, 표기 형식은 JSON-LD 1.1(2020년 7월 W3C 권고안)로 나뉘어 있습니다.
여기서 오해가 자주 생깁니다. 구조화 데이터는 검색 결과의 생김새에 관여하는 데이터이지 순위를 올리는 장치가 아닙니다. 구글 문서는 구조화 데이터 수동 조치에 대해 "리치 결과로 표시될 자격을 잃을 뿐, 웹 검색에서 페이지의 순위에는 영향을 주지 않는다"고 설명합니다.
JSON-LD는 어떻게 생겼나
JSON-LD 블록은 세 부분으로 이루어집니다. 감싸는 태그, 어휘를 가리키는 @context, 그리고 무엇에 대한 데이터인지 밝히는 @type입니다.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "구조화 데이터 입문 가이드",
"author": { "@type": "Person", "name": "홍길동" },
"datePublished": "2026-07-20",
"image": "https://example.com/cover.jpg"
}
</script>
type 속성값은 application/ld+json이어야 합니다. text/javascript로 적으면 브라우저가 그 안의 JSON을 코드로 실행하려다 오류를 내고, application/json으로 적으면 실행은 안 되지만 검색엔진이 구조화 데이터로 찾지 못합니다.
@context는 뒤에 나오는 headline·author 같은 이름을 schema.org 어휘로 읽으라는 선언입니다. @type은 이 데이터가 기사인지 상품인지 가게인지를 정합니다. 이 둘이 빠지면 나머지를 아무리 잘 적어도 해석되지 않습니다.
값이 또 다른 사물이면 중첩된 객체로 적습니다. 위 예시의 author가 그렇습니다. 사람 이름 하나를 적을 때도 { "@type": "Person", "name": "…" } 형태로 감싸는 이유입니다.
어디에 넣나
구글 문서는 JSON-LD를 "HTML 페이지의 <head>와 <body> 요소 안 <script> 태그에 들어가는 표기"로 설명합니다. 즉 둘 중 어디에 넣어도 됩니다.
같은 문서는 자바스크립트나 위젯이 나중에 삽입한 JSON-LD도 읽을 수 있다고 밝히고 있습니다. 정적 HTML에 직접 박아 넣기 어려운 환경이라면 이 점이 도움이 됩니다.
한 페이지에 여러 개를 넣어도 됩니다. 예를 들어 글 페이지에 Article 블록과 이동 경로(BreadcrumbList) 블록을 각각 두는 식입니다.
도구 없이 직접 만들고 검증하는 방법
순서는 네 단계입니다. 손으로도 충분히 할 수 있습니다.
1단계 — 유형을 고르고 필수 속성을 확인합니다
먼저 페이지가 무엇인지 정합니다(기사·상품·가게 등). 그다음 구글 검색 센터의 해당 기능 문서를 열어 필수 속성 표를 확인합니다. 유형마다 목록이 다르고, 문서가 갱신되기도 합니다.
2단계 — JSON을 씁니다
위 예시 형태로 @context와 @type을 먼저 적고, 확인한 속성을 채웁니다. 값을 모르는 속성은 빈 문자열로 남기지 말고 아예 빼는 편이 낫습니다. 빈 값은 잘못된 데이터로 읽힐 수 있습니다.
3단계 — 문법을 검사합니다
JSON은 쉼표 하나만 어긋나도 전체가 무효가 됩니다. 브라우저 개발자 도구(대개 F12) 콘솔에 아래를 넣으면 그 페이지에 실린 모든 JSON-LD 블록이 제대로 파싱되는지 바로 알 수 있습니다.
[...document.querySelectorAll('script[type="application/ld+json"]')]
.map(s => { try { return JSON.parse(s.textContent); } catch (e) { return "파싱 실패: " + e.message; } })
4단계 — 자격 여부를 확인합니다
구글 리치 결과 테스트(search.google.com/test/rich-results)는 페이지가 구글의 어떤 리치 결과 기능에 자격이 있는지를 알려 줍니다. 문법 자체만 보고 싶다면 schema.org의 마크업 검사기(validator.schema.org)를 씁니다. 두 도구는 보는 것이 다릅니다.
문제는 1~2단계입니다. 속성 이름과 중첩 구조를 매번 문서에서 찾아 옮겨 적어야 하고, 쉼표와 중괄호를 손으로 맞춰야 합니다.
저희 도구로 확인하기. 상단 탭에서 Article·Product·FAQ·LocalBusiness 중 하나를 고르고 폼을 채우면 JSON-LD가 실시간으로 완성됩니다. 비워 둔 항목은 결과에서 자동으로 빠지고, <script> 태그로 감싸기를 켜면 그대로 붙여 넣을 수 있는 형태로 나옵니다.
설치·회원가입 없이 브라우저 안에서 바로 생성되며, 입력한 내용은 서버로 전송되지 않습니다.
필수 속성과 권장 속성은 다릅니다
여기서 자주 어긋납니다. schema.org 어휘 자체에는 "필수"라는 표시가 없습니다. 필수 속성은 검색엔진이 특정 리치 결과 기능을 위해 따로 요구하는 목록입니다.
구글 문서 기준으로 정리하면 이렇습니다.
| 유형 | 구글이 요구하는 필수 속성 |
|---|---|
| Article(기사) | 없음 — 권장 속성만 있습니다 |
| Product(상품 스니펫) | name, 그리고 review·aggregateRating·offers 중 하나 |
| LocalBusiness(지역 비즈니스) | name, address |
Article에 필수 속성이 없다는 점이 의외로 보일 수 있습니다. 구글 문서는 "필수 속성은 없으며, 콘텐츠에 해당하는 속성을 넣으라"고 적고 있습니다. 대신 headline·image·datePublished·dateModified·author를 권장 속성으로 둡니다.
반대로 상품 스니펫은 이름만으로는 부족합니다. 리뷰·집계 평점·판매 정보 중 최소 하나가 있어야 자격이 생깁니다.
권장 속성은 많이 넣을수록 좋을 것 같지만, 구글 문서는 모든 권장 속성을 부실하게 채우기보다 적더라도 정확하게 채우는 편이 낫다고 명시합니다.
넣었는데 리치 결과가 안 보이는 이유
필수 속성을 다 채웠는데도 검색 결과가 그대로인 경우가 있습니다. 원인은 대체로 이 네 가지입니다.
| 상황 | 어떻게 되나 |
|---|---|
| 기능 자체가 없어짐 | 마크업은 유효해도 표시될 자리가 없습니다 |
| 화면에 없는 내용을 마크업 | 정책 위반이며 자격을 잃을 수 있습니다 |
| 필수 속성 누락 | 해당 기능의 자격 자체가 생기지 않습니다 |
| 자격은 있으나 미표시 | 어떤 형태로 보여 줄지는 검색엔진이 정합니다 |
첫 줄이 실제로 일어난 예가 FAQ입니다. FAQ 리치 결과는 2023년 8월에 정부·보건 분야의 널리 알려진 사이트로 대상이 좁혀졌고, 이후 2026년 5월 7일부터 구글 검색에 표시되지 않습니다.
FAQPage 마크업 자체는 여전히 유효한 schema.org 데이터입니다. 다만 구글 검색에서 FAQ 아코디언으로 보이는 일은 이제 없습니다.
두 번째 줄도 중요합니다. 구글 지침은 "페이지를 읽는 사람에게 보이지 않는 내용을 마크업하지 말라"고 못 박습니다. 화면에 없는 평점이나 가격을 JSON-LD에만 적어 넣는 것이 대표적인 위반입니다.
네 번째 줄이 이 글의 출발점입니다. 자격은 통과 여부이고, 노출은 검색엔진의 판단입니다. 리치 결과 테스트에서 자격이 확인되어도 실제 검색 결과에는 일반 텍스트로 나올 수 있습니다.
정리
- JSON-LD는
<script type="application/ld+json">안에 넣는 JSON 데이터이며,@context와@type이 반드시 있어야 합니다. - 넣는 위치는
<head>·<body>둘 다 가능하고, 한 페이지에 여러 블록을 둘 수 있습니다. - 필수 속성은 schema.org가 아니라 검색엔진이 기능별로 요구하는 목록입니다. Article은 필수 속성이 없고, 지역 비즈니스는 name과 address가 필수입니다.
- 권장 속성은 개수를 늘리기보다 정확하게 채우는 편이 낫습니다.
- 마크업이 올바르더라도 리치 결과 노출은 보장되지 않으며, FAQ처럼 기능이 사라지기도 합니다.
- 구조화 데이터는 검색 결과의 표시 방식에 관여하는 데이터이지 순위를 올리는 장치가 아닙니다.
설치·회원가입 없이 브라우저 안에서 바로 생성되며, 입력한 내용은 서버로 전송되지 않습니다.
자주 묻는 질문
JSON-LD를 head와 body 중 어디에 넣어야 하나요?
구글 문서는 JSON-LD를 <head>와 <body> 요소 안의 <script> 태그에 넣는 표기로 설명합니다. 둘 중 어디에 넣어도 읽힙니다. 같은 문서에 자바스크립트로 나중에 삽입한 JSON-LD도 읽을 수 있다고 적혀 있어, 템플릿을 직접 고치기 어려운 환경에서도 방법이 있습니다.
마크업을 넣으면 검색 순위가 올라가나요?
구조화 데이터는 순위가 아니라 검색 결과의 표시 방식에 관여하는 데이터입니다. 구글 문서는 구조화 데이터 수동 조치에 대해 "리치 결과로 표시될 자격을 잃을 뿐, 웹 검색에서 페이지 순위에는 영향을 주지 않는다"고 설명합니다. 또한 올바르게 마크업하더라도 리치 결과 표시를 보장하지 않는다고 명시합니다.
FAQ 마크업은 이제 넣을 필요가 없나요?
구글 검색의 FAQ 리치 결과는 2026년 5월 7일부터 표시되지 않습니다. 다만 FAQPage는 여전히 유효한 schema.org 유형이고, 마크업을 남겨 두어도 문제가 되지는 않습니다. 구글 검색에서 FAQ 아코디언 형태의 노출을 기대하고 넣는 것이라면 지금은 그 효과가 없다고 보시면 됩니다.
폼에 입력한 내용이 서버로 전송되나요?
아니요. 이 도구의 JSON-LD 생성은 전부 브라우저 안에서 이루어지며, 입력한 제목·주소·전화번호 같은 값은 서버로 전송되거나 저장되지 않습니다. 비워 둔 항목은 결과 JSON에서 자동으로 제외되므로, 채운 항목만 그대로 코드에 남습니다.