홈페이지 JSON-LD 적용 방법 — Organization·WebSite·Service를 @id로 연결하는 실제 코드

JSON-LD(JavaScript Object Notation for Linked Data)는 구조화 데이터를 <script type="application/ld+json"> 블록으로 HTML에 넣는 형식입니다. Schema.org 어휘를 씁니다.

구조화 데이터 형식은 세 가지가 있고, 실무에서는 사실상 하나로 정리됩니다.

JSON-LD는 화면 마크업과 떨어져 있습니다. 디자인을 바꿔도 데이터가 깨지지 않습니다. Google도 이 형식을 권장합니다.

홈페이지부터 적용하는 이유는 기준점이기 때문입니다. 조직 엔터티는 사이트 전체가 참조하는 루트입니다. 홈페이지에 Organization을 선언하고 @id를 부여해두면, 하위 페이지는 회사 정보를 반복해 적는 대신 그 @id만 가리키면 됩니다. 반대로 하위 페이지부터 손대면 같은 회사가 여러 엔터티로 쪼개집니다.

GEO 관점의 배경은 GEO란 무엇인가 가이드에 따로 정리했습니다.

변경 전 기준은 JSON-LD 도입 직전인 2026년 7월 10일 커밋 e519dc0입니다. 당시 app/page.tsx는 use client로 시작해 화면 상태와 인터랙션을 직접 관리했습니다. 이 파일에서 JsonLd, schema.org, application/ld+json 문자열 검색 결과는 0건이었습니다.

검증 범위는 밝혀두겠습니다. 위 결과는 app/page.tsx 한 파일 기준입니다. Next.js App Router에서는 layout.tsx나 공용 컴포넌트에서도 JSON-LD를 주입합니다. 페이지 단위 결론으로 쓰려면 검색 범위를 넓혀야 합니다.

이 상태를 크롤링 불가로 읽으면 안 됩니다. HTML 본문은 수집됩니다. 문제는 수집이 아니라 해석입니다.

페이지에 회사명이 몇 번 등장하든, 그것이 공식 조직명인지 본문 속 단어인지 판단할 근거가 없었습니다. 숫자가 대표번호인지, 서비스 설명이 이 회사 것인지 다른 회사 이야기인지도 마찬가지입니다. 사람은 맥락으로 압니다. 기계는 선언이 있어야 압니다.

커밋 해시는 내부 재현 기준입니다. 저장소가 비공개라 외부에서 직접 조회하지는 못합니다. 공개 검증이 필요하면 해당 시점에 보존된 렌더링 HTML로 대조하면 됩니다.

가장 먼저 만드는 노드입니다. 다른 모든 노드가 이걸 참조합니다.

{
  "@type": "Organization",
  "@id": "https://www.summitfeed.co.kr/#organization",
  "name": "써밋피드",
  "alternateName": ["SUMMITFEED", "써밋피드(SUMMITFEED)"],
  "url": "https://www.summitfeed.co.kr/",
  "logo": {
    "@type": "ImageObject",
    "@id": "https://www.summitfeed.co.kr/#logo",
    "url": "https://www.summitfeed.co.kr/images/brands/summitfeed-logo.png",
    "width": 1481,
    "height": 470,
    "caption": "써밋피드(SUMMITFEED)"
  },
  "identifier": {
    "@type": "PropertyValue",
    "name": "사업자등록번호",
    "value": "884-73-00630"
  },
  "taxID": "884-73-00630",
  "sameAs": ["https://summitfeed.tistory.com/"],
  "knowsAbout": [
    "Generative Engine Optimization",
    "AI 검색 최적화",
    "구조화 데이터",
    "Schema.org"
  ]
}

속성마다 이유가 있습니다.

`@id` — 이 조직의 고유 주소입니다. 홈페이지URL + #organization 형태를 씁니다. 다른 노드가 회사 정보를 반복해 적는 대신 이 값을 가리킵니다.

`alternateName` — 국문과 영문을 함께 넣습니다. "SUMMITFEED"로 찾든 "써밋피드"로 찾든 같은 엔터티로 이어집니다.

`logo` — 문자열 URL도 유효하지만 ImageObject를 쓰면 치수와 캡션을 함께 전달합니다. Google은 로고가 최소 112×112px일 것을 요구합니다.

`identifier`와 `taxID` — 사업자등록번호를 두 형태로 넣었습니다. identifier는 name: "사업자등록번호"라는 사람이 읽는 라벨이 붙고, taxID는 Schema.org 표준 속성이라 기계 판독이 확실합니다. 동명 법인과 구분되는 유일한 값이라 둘 다 넣을 값어치가 있습니다.

`sameAs` — 외부 공개 프로필을 연결합니다. 이 속성이 없으면 조직 정보가 전부 자기 선언으로만 남습니다.

여기서 실수하기 쉬운 지점이 있습니다. 조직 계정만 넣어야 합니다. 대표 개인 블로그를 Organization에 넣으면 "이 조직 = 개인 프로필"을 주장하는 셈입니다. 저희도 처음 목록을 뽑았을 때 브런치와 미디움이 개인 계정이라는 걸 놓칠 뻔했습니다.

`knowsAbout` — 전문 주제를 국영문 병기로 넣습니다. 영문 쿼리에서도 주제가 잡힙니다.

Organization 위에 사이트와 페이지를 얹습니다.

{
  "@type": "WebSite",
  "@id": "https://www.summitfeed.co.kr/#website",
  "url": "https://www.summitfeed.co.kr/",
  "publisher": { "@id": "https://www.summitfeed.co.kr/#organization" },
  "inLanguage": "ko-KR"
}

{
  "@type": "WebPage",
  "@id": "https://www.summitfeed.co.kr/#webpage",
  "url": "https://www.summitfeed.co.kr/",
  "isPartOf": { "@id": "https://www.summitfeed.co.kr/#website" },
  "about": { "@id": "https://www.summitfeed.co.kr/#organization" },
  "breadcrumb": { "@id": "https://www.summitfeed.co.kr/#breadcrumb" },
  "mainEntity": { "@id": "https://www.summitfeed.co.kr/#faq" },
  "primaryImageOfPage": { "@id": "https://www.summitfeed.co.kr/#logo" },
  "dateModified": "2026-08-17",
  "inLanguage": "ko-KR"
}

관계는 이렇게 읽힙니다.

URL 표기는 문자 단위로 통일해야 합니다. https://example.com과 https://example.com/은 사람 눈에 같아 보이지만 문자열 비교에서는 다른 값입니다. 저희는 자기 참조 URL 5곳 — canonical, Organization.url, WebSite.url, WebPage.url, BreadcrumbList.item — 의 trailing slash까지 맞췄습니다.

dateModified도 짚어두겠습니다. 이 값을 문자열로 박아두면 화면에 표시하는 갱신일과 반드시 어긋납니다. 상수 하나로 묶어 스키마와 푸터가 같은 값을 보게 만드세요. 뒤에서 다시 나올 이야기입니다.

{
  "@type": "Service",
  "@id": "https://www.summitfeed.co.kr/#service-geo",
  "name": "GEO 분석 및 실행",
  "serviceType": "Generative Engine Optimization",
  "provider": { "@id": "https://www.summitfeed.co.kr/#organization" },
  "areaServed": { "@type": "Country", "name": "대한민국" }
}

serviceType에는 정식 영문 명칭을 넣습니다. areaServed는 "KR" 같은 문자열보다 Country 객체가 명확합니다.

FAQPage는 규칙이 하나뿐입니다. 화면 렌더링 배열에서 생성하세요.

{
  "@type": "FAQPage",
  "@id": "https://www.summitfeed.co.kr/#faq",
  isPartOf: { "@id": "https://www.summitfeed.co.kr/#webpage" },
  mainEntity: faqItems.map((item) => ({
    "@type": "Question",
    name: item.question,
    acceptedAnswer: { "@type": "Answer", text: item.answer },
  })),
}

faqItems는 화면 FAQ 섹션이 렌더링하는 바로 그 배열입니다. 문안을 맞추는 게 아니라 어긋날 수 없는 구조로 만드는 것이 핵심입니다.

저희도 처음에는 스키마에 질문과 답변을 따로 적어뒀습니다. 그러다 화면 문구를 손보면서 스키마 쪽만 갱신됐고, 세 곳이 어긋났습니다. 그중 하나는 화면에 아예 없는 질문이 스키마에만 있는 상태였습니다. 배열을 map 하는 방식으로 바꾼 뒤로는 이 사고가 구조적으로 불가능해졌습니다.

FAQ 리치결과는 2026년 5월에 종료됐습니다

Google은 2026년 5월 7일부로 FAQ 리치결과를 검색 결과에서 제거했습니다. 6월에는 Search Console의 FAQ 검색 노출 유형과 리치 결과 보고서, 리치 결과 테스트 지원이 빠졌고, Search Console API 지원은 8월에 제거됩니다.

그런데도 FAQPage를 유지하는 이유는 리치결과가 아닙니다. FAQPage는 여전히 유효한 Schema.org 유형이고, 화면 Q&A와 기계 판독 데이터를 같은 출처로 묶어두는 역할을 합니다. 리치결과 노출만 보고 넣었다면 지금이 재검토 시점입니다.

조직 노드만으로는 "누가 썼는가"가 남지 않습니다. Person을 별도 노드로 만들고 worksFor로 연결했습니다.

{
  "@type": "Person",
  "@id": "https://www.summitfeed.co.kr/#founder",
  "name": "이승찬",
  "jobTitle": "대표",
  "url": "https://www.summitfeed.co.kr/about",
  "worksFor": { "@id": "https://www.summitfeed.co.kr/#organization" },
  "sameAs": [
    "https://brunch.co.kr/@609024f8b3744e2",
    "https://medium.com/@dltmdcks623100"
  ]
}

Organization 쪽에서는 founder로 이 노드를 가리킵니다. 양방향입니다.

이렇게 나누면 개인 채널과 조직 채널이 섞이지 않습니다. 브런치와 미디움은 대표 개인 계정이라 Person.sameAs에, 티스토리는 조직 계정이라 Organization.sameAs에 들어갑니다.

개인 계정을 회사 이름으로 바꾸는 방법도 있지만 권하지 않습니다. "누가 썼는가"에서는 회사명보다 사람 이름이 더 강한 신호입니다. 저자 엔터티를 지우면서 얻는 게 없습니다.

여기서부터가 실제로 겪은 이야기입니다.

첫 적용본은 6개 유형을 배열에 나열하는 방식이었습니다. 객체마다 @context를 반복해 적었고, @id는 세 개에만 붙어 있었습니다.

@id가 없으면 참조 대상이 되지 못합니다. Service는 provider로 Organization을 가리켰지만, 반대로 어디서도 Service를 가리키지 못했습니다. FAQPage는 관계 속성이 하나도 없어 완전히 떠 있었습니다.

문법 오류는 아닙니다. 리치결과 테스트도 통과합니다. 다만 "브랜드·사이트·페이지·서비스·FAQ의 관계를 전달한다"고 말할 수 있는 상태는 아니었습니다.

수정은 세 단계였습니다.

1. 배열을 단일 @context + @graph로 전환
2. 세 노드에 @id 부여
3. WebPage에서 breadcrumb·mainEntity로 참조, Organization에서 makesOffer로 Service 참조

{
  "@context": "https://schema.org",
  "@graph": [ /* 7개 노드 */ ]
}

@graph를 쓰면 @context를 한 번만 적고 노드 간 참조가 한눈에 들어옵니다. 결과적으로 유형은 6개에서 7개가 됐지만, 실제 변화는 고아 노드가 3개에서 0개가 된 것입니다.

이 절이 이 글에서 가장 실무적인 부분입니다.

한국어 페이지를 고치고 나서 영문 페이지를 점검했더니, 같은 문제가 다섯 번 남아 있었습니다. 하나씩 고칠 때마다 "이건 아까 고쳤는데"라는 생각이 들었습니다.

4번이 특히 눈에 띄었습니다. 한국어 푸터는 2026-08-17인데 영문 푸터는 July 24, 2026이었습니다. 같은 사이트의 같은 정보가 언어에 따라 3주 넘게 벌어져 있었습니다.

원인은 단순합니다. 한국어 화면을 보면서 고쳤기 때문입니다. 영문 페이지는 별도 파일에 별도 문구로 존재하는데, 한국어를 고칠 때 그쪽까지 열어보지 않았습니다.

언어별로 나눌 것과 공유할 것

다국어 JSON-LD에서 제일 헷갈리는 지점입니다. 기준은 "실체가 하나인가"입니다.

@id를 공유하는 노드는 속성 집합도 같아야 합니다. 같은 #service-geo인데 한국어에만 areaServed가 있으면, 같은 엔터티를 두 번 다르게 설명하는 셈입니다.

여기에 하나 더. 공유 노드의 값이 한국어라면 영문 페이지에서도 한국어로 나옵니다. Person의 name이 그렇습니다. 실체가 하나라 값을 바꾸면 안 되고, 대신 alternateName으로 영문 표기를 더하는 편이 맞습니다.

코드가 존재하는 것과 검색 시스템이 읽는 것은 다릅니다.

useEffect 안에서 JSON-LD를 주입하면 브라우저 DOM에는 들어가지만 서버가 반환하는 초기 HTML에는 없습니다. 브라우저 콘솔에서 `document.querySelectorAll`로 확인하는 것도 증명이 되지 않습니다. 하이드레이션이 끝난 뒤의 DOM을 보기 때문입니다.

확인은 curl로 합니다.

curl -s https://www.summitfeed.co.kr/ | grep -o '"@type":"[^"]*"' | sort | uniq -c

현재 한국어 홈페이지 실행 결과입니다.

스크립트 블록은 1개, 최상위 노드는 7개입니다. Question과 Answer가 각각 9개인 것은 화면 FAQ 9문항과 정확히 일치한다는 뜻입니다. ContactPoint, ImageObject, PropertyValue, Country는 상위 노드 안에 들어간 하위 객체입니다.

세 페이지를 같은 방식으로 확인한 결과입니다.

검증 도구는 두 가지를 함께 씁니다. 리치결과 테스트는 Google 리치결과 자격을, Schema.org Validator는 JSON-LD 문법 자체를 봅니다. Google이 지원하지 않는 유형을 썼을 때 후자가 문법 오류를 잡습니다. 하나만 돌리면 놓칩니다.

1. 화면에 없는 내용을 스키마에만 넣는 경우

Google 구조화 데이터 일반 가이드라인은 독자에게 보이지 않는 콘텐츠의 마크업을 명시적으로 금지합니다. FAQ 리치결과가 종료된 지금도 이 조항은 유효하고, 위반은 수동 조치 대상입니다. 화면에 없는 별점이나 가격을 넣는 것도 같은 유형입니다.

2. @id 없이 같은 정보를 스키마마다 반복 기입

회사명·URL·로고를 Organization, WebSite, Article에 각각 적으면 같은 회사가 여러 엔터티로 쪼개집니다. @id를 부여하고 참조하세요.

3. 상대경로 URL

/images/logo.png처럼 적으면 페이지 위치에 따라 해석이 달라집니다. url·@id·logo는 전부 https 절대경로여야 합니다.

4. useEffect 안에서 JSON-LD 주입

클라이언트 실행 후 만들어지는 값은 초기 HTML에 없습니다. 서버 렌더링 경로에서 출력되도록 구성하세요.

5. 날짜와 URL을 문자열로 박아두기

dateModified를 문자열로 적으면 화면 갱신일과 반드시 어긋납니다. @id도 마찬가지입니다.

저희는 영문 파일에서 @id 다섯 곳이 문자열로 박혀 있는 것을 뒤늦게 찾았습니다. 값 자체는 맞았지만, 경로가 바뀌면 거기만 남습니다. 상수로 묶는 데 5분이면 됩니다.

6. grep으로 확인할 때 배열 타입을 놓치는 경우

"@type":"[^"]*" 패턴은 "@type":["Article","TechArticle"] 같은 배열을 잡지 못합니다. 콜론 뒤가 [라서 매칭이 안 됩니다. 노드가 빠진 줄 알고 다시 넣으면 중복됩니다.

배열 타입은 따로 확인하세요.

curl -s <URL> | grep -o '"@type":\[[^]]*\]'

7. 다국어 사이트에서 한 언어만 고치기

앞 절 전체가 이 이야기입니다. 한국어를 고쳤으면 영문도 같은 날 확인하세요. 언어별 파일이 나뉘어 있으면 반드시 한쪽이 뒤에 남습니다.

훑어보는 용도의 표입니다. 각 항목의 설명은 앞 절에 있습니다.

유형 수를 늘리는 게 목표는 아닙니다. 화면에 있는 정보만 표현하는 것, 그리고 @id로 상호 참조해 중복 선언을 없애는 것이 기준입니다.

• 회사명·영문명·공식 URL·이메일·로고가 사이트 전체에서 일치하는가
• 자기 참조 URL이 canonical을 포함해 trailing slash까지 같은 문자열인가
• 스키마의 서비스와 FAQ가 실제 화면 본문에 존재하는가
• 모든 노드에 @id가 있고 참조되지 않는 고아 노드가 없는가
• 날짜와 @id가 상수를 참조하는가, 문자열로 박혀 있지 않은가
• 다국어 사이트라면 위 항목을 언어별로 각각 확인했는가
• 배포 후 curl로 초기 HTML에 application/ld+json이 출력되는가
• 리치결과 테스트와 Schema.org Validator를 모두 통과했는가

마지막에서 세 번째 항목이 저희가 가장 많이 놓친 부분입니다.

더 넓은 범위의 점검은 AI 검색 노출 홈페이지 진단 25가지에 정리했습니다.