구조·마크업 · 공식 문서
JSON-LD 생성기 결과 점검 순서와 스키마 마크업 예시
생성기로 뼈대를 만들어도 되지만, 구글 기능 문서의 필수 속성과 대조하고 값이 화면 내용과 같은지 고친 뒤 써야 합니다. 구글은 품질 가이드라인을 자동 도구로 검사하기 어렵다고 적었으므로, 테스트 통과 뒤에도 내용 대조는 사람이 합니다.
JSON-LD 생성기는 유형을 고르고 칸을 채우면 코드를 만들어 줍니다. 문법은 맞는 코드가 나오지만, 값이 우리 페이지와 맞는지는 사람이 페이지를 보고 맞춰야 합니다.
확인한 구글 공식 문서는 생성기를 따로 다루지 않고, 구조화 데이터를 무엇에 맞춰야 하는지를 적었습니다. 그 기준으로 점검 순서를 세웠습니다.
발견 01
생성기는 문법을 맞춰 주고, 내용이 페이지와 맞는지는 사람이 대조합니다
These quality guidelines are not easily testable using an automated tool.
이 품질 가이드라인은 자동 도구로 쉽게 시험할 수 없다.
| 기준 | 구글 원문 |
|---|---|
| 기준 문서 | Most Search structured data uses schema.org vocabulary, but you should rely on the Google Search Central documentation as definitive for Google Search behavior, rather than the schema.org documentation.검색 구조화 데이터 대부분은 schema.org 어휘를 쓰지만, 구글 검색 동작의 기준으로는 schema.org 문서가 아니라 구글 검색 센터 문서를 따라야 한다. |
| 필수 속성 | You must include all the required properties for an object to be eligible for appearance in Google Search with enhanced display.구글 검색의 꾸며진 표시 대상이 되려면 객체의 필수 속성을 모두 넣어야 한다. |
| 기능 고르기 | To make your site eligible for appearance as one of these rich results, follow the guide to learn how to implement structured data on your site.사이트가 이런 리치 결과로 표시될 자격을 갖추려면, 안내를 따라 사이트에 구조화 데이터를 구현하는 법을 익힌다. |
| 페이지 내용과 같게 | Use variables to extract the structured data from the page instead of duplicating the information in GTM.GTM 에 정보를 복제하지 말고 변수로 페이지에서 구조화 데이터를 뽑아 쓴다. |
생성기의 칸은 schema.org 어휘를 따르고, 구글 기능 문서의 필수 속성과 다를 수 있습니다. 그래서 칸을 다 채워도 구글 기준의 필수 속성이 빠질 수 있습니다.
태그 관리자 문서의 원칙도 같습니다. 값을 복사해 붙이면 페이지와 어긋날 위험이 커진다고 적었습니다.
발견 02
생성기 결과는 9단계 순서로 고쳐 씁니다
| 순서 | 점검 | 하는 법 | 공식 문서 원문 |
|---|---|---|---|
| 1 | 유형이 페이지와 맞나 | 페이지가 실제로 다루는 것(회사·글·상품)과 @type 이 같은지 봅니다. | Your structured data must be a true representation of the page content.구조화 데이터는 페이지 콘텐츠를 사실대로 나타내야 한다. |
| 2 | 구글 문서의 필수 속성 | 생성기 항목이 아니라 그 기능의 구글 문서 필수 속성 목록과 대조합니다. | Most Search structured data uses schema.org vocabulary, but you should rely on the Google Search Central documentation as definitive for Google Search behavior, rather than the schema.org documentation.검색 구조화 데이터 대부분은 schema.org 어휘를 쓰지만, 구글 검색 동작의 기준으로는 schema.org 문서가 아니라 구글 검색 센터 문서를 따라야 한다. |
| 3 | 예시값·빈 값 지우기 | "Your Company" 같은 기본값과 비어 있는 줄을 지웁니다. 정확한 값이 없는 권장 속성은 빼는 편이 낫습니다. | However, it is more important to supply fewer but complete and accurate recommended properties rather than trying to provide every possible recommended property with less complete, badly-formed, or inaccurate data.덜 완전하거나 형식이 틀리거나 부정확한 데이터로 권장 속성을 모두 채우려 하기보다, 적더라도 완전하고 정확한 권장 속성을 주는 것이 더 중요하다. |
| 4 | 화면에 보이는 값과 같나 | 이름·가격·주소가 페이지 화면의 표기와 글자까지 같은지 봅니다. | Don't mark up content that is not visible to readers of the page.페이지를 읽는 사람에게 보이지 않는 콘텐츠는 마크업하지 않는다. |
| 5 | 값의 출처를 한 곳으로 | 여러 페이지에 쓰는 코드라면 값을 손으로 붙여 넣지 말고 페이지 데이터에서 받아 오게 합니다. | Duplicating the information in GTM increases the risk of having a mismatch between page content and the structured data inserted using GTM.GTM 에 정보를 복제하면 페이지 내용과 GTM 으로 넣은 구조화 데이터가 어긋날 위험이 커진다. |
| 6 | 이미지 URL | logo·image 의 URL 이 절대 URL 이고 robots.txt 로 차단되어 있지 않은지 봅니다. | All image URLs specified in structured data must be crawlable and indexable.구조화 데이터에 적은 이미지 URL은 모두 크롤링과 색인이 가능해야 한다. |
| 7 | 주석 지우기 | 생성기나 개발자가 남긴 주석을 JSON-LD 안에서 지웁니다. | Be sure to remove any comments from JSON-LD before publishing your final page.최종 페이지를 게시하기 전에 JSON-LD 안의 주석을 모두 지운다. |
| 8 | URL 로 테스트 | 배포한 페이지 URL 을 리치 결과 테스트에 넣습니다. 코드 입력은 배포 전 확인용으로만 씁니다. | We recommend that you use the URL input instead of the code input because there are JavaScript limitations when using the code input (for example, CORS restrictions).코드 입력은 자바스크립트 제약(예: CORS)이 있으므로 코드 입력보다 URL 입력을 권한다. |
| 9 | 지원 밖 유형 | 리치 결과 테스트가 다루지 않는 유형은 스키마 마크업 검사기와 렌더링된 HTML 로 봅니다. | If you are testing a structured data type that is not supported by the Rich Results test, check the rendered HTML.리치 결과 테스트가 지원하지 않는 유형을 검사한다면 렌더링된 HTML 을 확인한다. |
| 검사 도구 | 구글 원문 |
|---|---|
| 어느 도구부터 | Google recommends that you start with the Rich Results Test to see what Google rich results can be generated for your page. For generic schema validation, use the Schema Markup Validator to test all types of schema.org markup, without Google-specific validation.구글은 먼저 리치 결과 테스트로 페이지에서 어떤 구글 리치 결과가 생성될 수 있는지 보라고 권한다. 일반적인 스키마 검증에는 구글 전용 검증 없이 모든 schema.org 마크업을 검사하는 스키마 마크업 유효성 검사 도구를 쓴다. |
| 코드로 검사 | You can test an arbitrary code snippet using this tool.이 도구로 임의의 코드 조각도 검사할 수 있다. |
발견 03
회사 홈페이지 Organization 예시에서는 필드 7개 중 6개를 고칩니다
| 필드 | 생성기 기본값(예) | 고친 값(예) | 이유 |
|---|---|---|---|
| @type | Organization | Organization | 회사 홈페이지라 그대로 둡니다. |
| name | Your Company | 예시데이터 | 홈페이지 <title>·로고 옆 표기와 같은 이름 |
| url | https://www.example.com | https://example.com/ | 실제로 열리는 캐노니컬 홈페이지 URL |
| logo | https://www.example.com/logo.png | https://example.com/images/logo-512.png | The image must be 112x112px, at minimum.로고 이미지는 최소 112x112px 이어야 한다. |
| telephone | +1-000-000-0000 | +82-2-0000-0000 | Be sure to include the country code and area code in the phone number.전화번호에는 국가번호와 지역번호를 넣는다. |
| sameAs | ["", ""] | ["https://www.linkedin.com/company/example"] | For example, a URL to your organization's profile page on a social media or review site.예를 들어 소셜 미디어나 리뷰 사이트에 있는 조직 프로필 페이지 URL. |
| address | Street, City, Zip | 줄 삭제 | 화면에 주소가 없으면 마크업하지 않습니다. |
| Organization 기준 | 구글 원문 |
|---|---|
| 필수 속성 | There are no required properties; instead, we recommend adding as many properties that are relevant to your organization.필수 속성은 없다. 대신 조직에 해당하는 속성을 되도록 많이 넣으라고 권한다. |
고친 코드는 홈페이지 <head> 의 <script type="application/ld+json"> 안에 넣습니다. 사이트 이름을 함께 알리려면 WebSite 노드를 더해 @id 로 잇습니다.
노드를 잇는 법은 「JSON-LD @graph와 @id」 편에 자세히 적었습니다.
발견 04
B2B·B2C·B2G 사이트마다 생성기 결과에서 가장 많이 고칠 칸이 다릅니다
예시 ① 세미나 페이지를 자주 여는 솔루션 회사(B2B)
한 번 만든 행사 코드는 다음 행사 페이지에 그대로 복사되기 쉽습니다. 행사마다 일시·장소를 그 페이지 값으로 다시 채우고, 끝난 행사의 마크업은 페이지와 함께 정리합니다.
예시 ② 상품 수백 개를 파는 쇼핑몰(B2C)
상품 하나로 만든 생성기 코드를 템플릿에 붙이면 모든 상품이 같은 가격을 갖게 됩니다. 가격·재고 값은 상품 데이터에서 받아 오게 바꿉니다.
예시 ③ 기관 소개 페이지를 고치는 공공기관 누리집(B2G)
생성기의 주소 칸이 영어 주소 순서라면 도로명 주소를 칸에 맞게 나눠 넣습니다. 기관명·대표번호는 화면 표기와 같게 고치고, 화면에 없는 항목은 지웁니다.
그럼 생성기 코드를 받았다면 무엇부터 하나요?
- 코드의 @type 을 보고, 구글 검색 갤러리에서 그 기능 문서를 엽니다.
- 문서의 필수 속성 목록을 옆에 두고 코드의 키를 하나씩 대조합니다.
- 기본값·빈 값이 남은 줄을 지우고, 남은 값을 페이지 화면과 글자까지 맞춥니다.
- 위 9단계 순서로 이미지 URL·주석을 정리합니다.
- 배포한 URL 을 리치 결과 테스트에 넣어 확인하고, 서치 콘솔 리치 결과 보고서를 몇 주 지켜봅니다. 검사 도구 결과 읽는 법은 「구조화 데이터」 편에 자세히 적었습니다.
조사 방법
- Google Search Central 「Generate structured data with JavaScript」 (문서 수정일 2025-12-10) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/generate-structured-data-with-javascript
- Google Search Central 「Introduction to structured data markup in Google Search」 (문서 수정일 2025-12-10) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data
- Google Search Central 「General structured data guidelines」 (문서 수정일 2026-07-10) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/sd-policies
- Google Search Central 「Structured data markup that Google Search supports」 (문서 수정일 2026-10-16) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/search-gallery
- Google Search Central 「Organization (Organization) structured data」 (문서 수정일 2026-09-08) · 최종 확인일 2026-10-25 · https://developers.google.com/search/docs/appearance/structured-data/organization
- Google Search Central 「Test your structured data」 · 최종 확인일 2026-10-18 · https://developers.google.com/search/docs/appearance/structured-data
- Search Console Help 「Rich Results Test」 · 최종 확인일 2026-10-18 · https://support.google.com/webmasters/answer/7445569
- 점검 순서 9단계는 위 문서들이 구조화 데이터에 요구한 것을 생성기 결과를 고치는 순서로 묶은 것입니다. 묶는 방식은 편집 판단입니다.
- 구글 문서는 생성기를 따로 다루지 않아, 특정 생성기 도구의 평가는 이 편의 범위 밖에 두었습니다.
- 예시 ①②③과 Organization 예시 값은 이해를 돕기 위해 만든 가상 상황이며, 실제 기업·기관의 사례가 아닙니다.
- 원문은 영어판(hl=en)이고, 도구·문서 이름은 같은 문서 한국어판(hl=ko) 표기를 따랐습니다.