JSON-LD 문법 기초 | 봇에게 데이터의 정체를 알려주는 법
이 글은 "AEO 입문: AI에게 읽히는 기술" 시리즈의 여섯 번째 글입니다.
1편에서는 크롤링과 인덱싱의 차이를, 2편에서는 봇이 HTML을 어떤 순서로 읽는지를, 3편에서는 robots.txt를, 4편에서는 sitemap.xml을, 5편에서는 canonical 태그를 다뤘습니다.
지금까지는 봇이 페이지에 접근하고 읽는 과정을 살펴봤습니다.
이번 편부터는 한 단계 더 나아갑니다.
봇이 HTML을 읽긴 읽었는데, 페이지 안의 텍스트가 정확히 무엇을 뜻하는지 확신할 수 있을까요?
"39,000원"이라는 텍스트를 사람은 가격이라고 바로 알지만, 봇은 그게 가격인지, 모델 번호인지, 전화번호인지 구분하지 못합니다.
JSON-LD는 이 추측을 제거하는 도구입니다.
"이건 가격이고, 이건 상품명이고, 이건 리뷰 평점이다"를 봇이 100% 확실하게 이해할 수 있는 형식으로 적어주는 것입니다.
JSON-LD의 정체 — 봇을 위한 데이터 명함
JSON-LD는 JSON for Linking Data의 약자입니다.
페이지에 있는 데이터가 무엇인지를 봇에게 명확히 알려주는 구조화 데이터 포맷입니다.
구성 요소는 세 가지입니다.
@context — 어휘 사전을 지정합니다. "내가 쓰는 단어들의 정의는 schema.org에서 가져왔어"라는 선언입니다.
"@context": "https://schema.org"@type — 이 데이터가 무엇인지 선언합니다. 상품(Product)인지, 글(Article)인지, FAQ인지.
"@type": "Product"속성(properties) — 해당 타입에 맞는 구체적 정보입니다. Product라면 name, description, image 같은 것들이 속성입니다.
이 세 가지가 합쳐지면 이런 구조가 됩니다.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Product",
"name": "오가닉 코튼 티셔츠",
"description": "100% 유기농 면 소재의 베이직 티셔츠",
"brand": {
"@type": "Brand",
"name": "브랜드 A"
}
}
</script>여기서 짚어볼 점이 두 가지 있습니다.
배치 위치: <head> 안에 넣든 <body> 끝에 넣든 기능적 차이는 없습니다. 구글은 페이지 어디에 있든 파싱합니다. 다만 관례적으로 <head> 안에 넣는 것이 일반적입니다.
HTML과의 관계: JSON-LD는 페이지에 보이지 않습니다. <script> 태그 안에 들어가기 때문에 사용자에게는 렌더링되지 않고, 오직 봇만 읽습니다. 2편에서 다룬 HTML 파싱 순서를 떠올려보면, 봇이 <head>를 읽을 때 이 <script>도 함께 읽어가는 것입니다.
왜 JSON-LD인가 — 세 가지 방식 비교
구조화 데이터를 삽입하는 방식은 세 가지가 있습니다.
Microdata — HTML 태그 안에 속성으로 직접 삽입하는 방식입니다. 예를 들면 <span itemprop="price">39,000</span>처럼 HTML 코드와 데이터가 뒤섞입니다. 기존 HTML 템플릿을 직접 건드려야 하기 때문에 유지보수가 어렵고, 커머스 플랫폼에서는 리스크가 큽니다.
RDFa — 역시 HTML 속성 방식입니다. Microdata와 비슷한 문제를 안고 있습니다.
JSON-LD — HTML과 완전히 분리된 독립 블록입니다. <script> 태그 하나만 추가하면 끝입니다. 기존 HTML 코드를 전혀 건드릴 필요가 없습니다.
구글은 공식적으로 JSON-LD를 권장합니다. 이유는 명확합니다.
기존 코드와 분리되어 있으니 삽입, 수정, 삭제가 안전합니다. 복사-붙여넣기만으로 적용할 수 있고, 카페24나 고도몰 같은 플랫폼에서 "헤더 스크립트 삽입" 기능을 통해 쉽게 추가할 수 있습니다.
컨설팅 관점에서도 차이가 큽니다. Microdata를 제안하면 "기존 HTML 템플릿을 건드려야 합니다"라고 말해야 합니다. JSON-LD를 제안하면 "스크립트 한 블록만 추가하면 됩니다"로 끝납니다. 실행 난이도가 낮을수록 클라이언트 수용률은 올라갑니다.
중첩 객체(Nesting) — 현실 데이터는 단층이 아니다
JSON-LD에서 가장 중요한 문법 개념이 중첩(Nesting)입니다.
현실의 데이터는 단순하지 않습니다. 상품에는 가격이 있고, 가격에는 통화와 재고 상태가 있고, 리뷰가 있고, 리뷰에는 평점과 작성자가 있습니다. 이런 관계를 JSON-LD에서는 객체 안에 객체를 넣어서 표현합니다.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "프리미엄 세럼",
"brand": {
"@type": "Brand",
"name": "브랜드 B"
},
"offers": {
"@type": "Offer",
"price": "52000",
"priceCurrency": "KRW",
"availability": "https://schema.org/InStock",
"seller": {
"@type": "Organization",
"name": "브랜드 B 공식몰"
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"reviewCount": "328"
}
}이 하나의 JSON-LD 블록 안에 세 단계의 중첩이 들어가 있습니다.
Product → Brand (이 상품의 브랜드는 무엇인가)Product → Offer → Organization (이 상품의 판매 조건과 판매자는 누구인가)Product → AggregateRating (이 상품의 전체 평점은 얼마인가)
왜 이게 중요할까요? 구글이 리치 결과를 만들 때, 이 중첩 관계를 정확히 읽어야 "이 상품은 52,000원이고, 재고 있고, 평점 4.7이고, 리뷰 328개"라는 정보를 검색 결과에 한 번에 보여줄 수 있습니다. 중첩이 깨지거나 빠지면 리치 결과가 불완전하게 나오거나 아예 표시되지 않습니다.
카페24에서 JSON-LD 넣는 실제 경로
"우리 쇼핑몰에서도 넣을 수 있나요?"라는 질문에 대한 답부터 하겠습니다. 카페24, 고도몰, 아임웹 모두 가능합니다. 경로를 모르는 것이지, 기능이 없는 게 아닙니다.
카페24 기준으로 두 가지 경로가 있습니다.
전역 스키마 — 코드 직접입력
카페24 관리자 → 기본 설정 → 고급설정 → 코드 직접입력
이 영역에 <script type="application/ld+json"> 블록을 넣으면 모든 페이지에 공통으로 적용됩니다. 사이트 전체에 해당하는 Organization(회사 정보)이나 WebSite(사이트 정보) 같은 스키마를 넣기에 적합합니다.
상품별 동적 스키마 — 스킨 편집
카페24 관리자 → 디자인 → 스킨 편집 → product/detail.html
Product 스키마처럼 상품마다 이름, 가격, 재고가 다른 정보는 이 템플릿 파일에서 카페24 치환코드를 활용합니다.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "{$name}",
"image": "{$image}",
"offers": {
"@type": "Offer",
"price": "{$price}",
"priceCurrency": "KRW"
}
}{$name}, {$price} 같은 치환코드는 카페24가 각 상품의 실제 데이터로 자동 교체합니다. 상품이 수천 개여도 템플릿 하나로 전부 커버할 수 있습니다.
흔한 오해 — "개별 페이지 SEO 태그"에 넣으면 되지 않나?
카페24 관리자에 "개별 페이지 SEO 태그"라는 메뉴가 있습니다. Title, Description, Author, Keywords를 설정하는 영역인데, 여기에 JSON-LD를 넣으면 될 것 같다는 오해가 있습니다.
이 영역은 meta 태그 전용입니다. JSON-LD는 <script> 태그인데, 이 입력 폼에 넣으면 카페24가 meta 태그 값으로 처리하려다 깨지거나 무시합니다. 또한 경로가 /product/detail.html로 고정되어 있어서 상품 A와 상품 B를 구분하는 동적 처리도 불가능합니다.
정리하면 이렇습니다.
코드 직접입력 → 전역 JSON-LD (Organization, WebSite 등)
스킨 편집 > product/detail.html → 상품별 동적 JSON-LD (Product, Offer 등)
개별 페이지 SEO 태그 → meta 태그 전용, JSON-LD 불가
고도몰과 아임웹도 구조는 유사합니다. 템플릿 편집 영역에 스크립트를 삽입하고, 각 플랫폼이 제공하는 치환코드(변수)를 사용해서 동적으로 데이터를 채우는 방식입니다.
검증 — 작성한 JSON-LD가 제대로 작동하는지 확인하기
JSON-LD를 작성했다면 반드시 검증해야 합니다. 두 가지 도구가 있습니다.
Google Rich Results Test (search.google.com/test/rich-results)
URL이나 코드 스니펫을 넣으면 구글이 이 JSON-LD를 리치 결과로 인식하는지 테스트합니다. "적격" 또는 "부적격" 판정과 함께 어떤 필드가 누락되었는지 알려줍니다. 실무에서 가장 많이 사용하는 도구입니다.
Schema Markup Validator (validator.schema.org)
schema.org 문법 자체가 올바른지 검증합니다. 구글 리치 결과 적격 여부와는 별개로, 문법적 오류를 잡아줍니다.
두 도구의 역할이 다르다는 점을 기억해두면 좋습니다. Schema Validator는 "문법이 맞는가"를, Rich Results Test는 "구글 검색에서 리치 결과로 표시될 자격이 있는가"를 판단합니다.
진단 실무 흐름
사이트를 진단할 때는 이 순서로 확인합니다.
먼저 사이트 URL을 Rich Results Test에 넣어봅니다.
구조화 데이터가 아예 없으면 → "구조화 데이터 미적용 상태"로 진단합니다.
있는데 오류가 있으면 → 구체적으로 어떤 필드가 문제인지 파악합니다.
있고 정상이면 → 누락된 권장 필드가 있는지 추가로 체크합니다.
브라우저 콘솔 진단 스크립트
검증 도구 외에, 아무 사이트에서 바로 JSON-LD를 확인할 수 있는 콘솔 스크립트도 있습니다.
브라우저 개발자 도구(F12)를 열고 Console 탭에 아래 코드를 입력하면 됩니다.
document.querySelectorAll('script[type="application/ld+json"]').forEach((el, i) => {
console.log(`--- JSON-LD #${i + 1} ---`);
try {
console.log(JSON.parse(el.textContent));
} catch(e) {
console.log('파싱 에러:', e.message);
console.log('원본:', el.textContent);
}
});이 스크립트는 페이지에서 type="application/ld+json"인 script 태그를 전부 찾아서 JSON으로 파싱한 결과를 보여줍니다. 문법 오류가 있으면 에러 메시지와 원본 텍스트를 함께 출력합니다.
커머스 사이트 몇 곳을 방문해서 직접 실행해보면 감이 잡힐 것입니다. 어떤 사이트는 JSON-LD가 잘 들어가 있고, 어떤 사이트는 아예 없습니다. 특히 카페24 기반 쇼핑몰을 비교해보면 대부분 JSON-LD 자체가 없는 상태라는 걸 확인할 수 있을 것입니다.
JSON-LD가 있으면 무엇이 달라지는가
JSON-LD가 적용된 사이트와 아닌 사이트의 차이는 검색 결과에서 바로 드러납니다.
JSON-LD가 있으면 구글 검색에서 리치 결과가 표시될 수 있습니다. 상품 검색 시 가격, 별점, 리뷰 수, 재고 여부가 검색 결과에 바로 노출됩니다. 경쟁사 상품이 "4.8★ (328) · ₩52,000 · 재고 있음" 같은 정보와 함께 보이는데, 내 상품은 제목과 설명만 달랑 나온다면 클릭률 차이가 날 수밖에 없습니다.
AI 엔진 관점에서도 마찬가지입니다. "이건 52,000원짜리 세럼이다"를 HTML 텍스트에서 추측하는 것과 JSON-LD에서 확정적으로 읽는 것은 신뢰도가 다릅니다. JSON-LD가 있는 사이트의 상품 정보를 AI가 더 정확하게 인용할 가능성이 높아집니다.
이번 편에서는 JSON-LD의 기본 문법과 구조를 다뤘습니다. 다음 편에서는 커머스에서 가장 중요한 Product 스키마의 필수 필드와 권장 필드를 상세하게 살펴보겠습니다.