Codex로 하는 SEO Schema JSON-LD: 복사 가능한 SKILL.md와 검증 워크플로

결론: Schema는 페이지 사실을 구조화해 옮긴 것이어야 합니다

SEO Schema JSON-LD용 Codex SKILL.md 프롬프트를 찾고 있다면 아래에서 바로 복사할 수 있습니다. 다만 코드보다 먼저 지켜야 할 원칙이 있습니다. 구조화 데이터는 방문자가 페이지에서 확인할 수 있는 사실을 표현해야 합니다. 가능한 한 많은 속성을 채운 JSON을 만드는 수단이 아닙니다.

Codex는 유형을 제안하거나 JSON-LD를 작성하기 전에 페이지, 콘텐츠 데이터, 기존 마크업을 검토할 수 있습니다. 이 순서가 중요합니다. "추가할 수 있는 Schema를 모두 넣어 달라"는 모호한 요청은 aggregateRating, 가격, 작성자, 게시일 같은 값을 근거 없이 만들기 쉽습니다. JSON 문법이 맞더라도 페이지를 잘못 표현할 수 있습니다.

Google은 사이트 구조상 가능하다면 구현과 유지 관리가 비교적 쉬운 JSON-LD를 권장합니다. 동시에 마크업은 해당 페이지를 설명하고, 사용자에게 보이는 콘텐츠와 일치하며, 정확해야 한다고 명시합니다. Rich Results Test를 통과해도 리치 결과가 표시된다는 보장은 없습니다.

보조 객체보다 먼저 페이지의 주요 유형을 고르세요

먼저 "방문자가 이 페이지에서 주로 보는 것은 무엇인가?"를 묻습니다. 그 답이 기본 Schema.org 유형입니다. 이동 경로, 조직 정보, 비디오는 같은 페이지에서 사용자에게 보이는 정보를 설명할 때만 주요 객체를 보조할 수 있습니다.

Schema.org의 어휘는 Google의 리치 결과 기능보다 훨씬 넓습니다. Google 검색을 위한 구현에서는 "Schema.org에 속성이 있다"는 사실보다 대상 기능의 최신 Google Search Central 문서를 우선해야 합니다.

페이지 목적부터 확인하세요. 유형은 보이는 사실을 따라야 하며 그 반대가 아닙니다.

더 안전한 Codex 워크플로에는 네 개의 관문이 있습니다

1. 사실 인벤토리: 보이는 페이지 문구, 페이지에 렌더링되는 신뢰할 수 있는 CMS 필드, 또는 사용자가 명시적으로 확인한 데이터에서만 추출합니다. 후보 필드를 확인됨, 누락됨, 사람의 확인 필요로 표시합니다.
2. 유형 결정: 페이지의 중심 목적에 맞는 주요 유형을 하나 고릅니다. 그럴듯한 유형을 한 응답에 쌓지 말고, 대안이 있다면 이유를 설명합니다.
3. 코드와 매핑: 출력한 JSON-LD의 각 값에 출처를 연결합니다. 알 수 없는 속성은 자리 표시자로 채우지 말고 생략합니다.
4. 검증과 배포: JSON 문법, 기능별 요구 사항, 렌더링된 DOM, URL Inspection, 관련 Search Console 보고서를 확인합니다.

아래 Skill은 이 관문을 명시합니다. Codex가 먼저 감사하고 다음에 코드를 바꾸도록 하면, 보기에는 유효하지만 페이지 내용과 어긋나는 마크업을 막을 수 있습니다.

그대로 복사할 수 있는 SEO Schema JSON-LD Codex Skill (SKILL.md)

아래 내용을 자신의 Skill 설정으로 저장하세요. 기기 디렉터리, 사용자 이름, 액세스 토큰, 환경 변수 값, 비공개 경로는 포함하지 않습니다. Codex가 출력에서 민감한 컨텍스트를 제거하도록 지시합니다.

---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---

# SEO Schema JSON-LD

Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.

## Primary rule

Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.

## Privacy and output safety

- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.

## Required workflow

### 1. Inspect before generating

Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:

- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.

For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.

### 2. Choose the narrowest suitable type

Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.

Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.

For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.

### 3. Apply strict data guardrails

Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:

- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.

Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.

### 4. Produce the implementation

Return these sections in order:

1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.

If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.

## JSON-LD quality checks

Before finalizing, verify all of the following:

- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.

## Limitations to state plainly

Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.

승인 관문을 두고 Skill 사용하기

"이 페이지에 Schema를 추가해 줘"에서 멈추지 마세요. 페이지와 승인 기준을 Codex에 전달합니다. 다음 프롬프트가 좋은 시작점입니다.

Use the SEO Schema JSON-LD skill to review this article page.

Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.

대규모 템플릿에서도 "먼저 사실 인벤토리와 유형 결정을 반환"하는 관문을 유지하세요. 짧은 검토 단계가 하나 늘어나지만, 잘못된 가정이 수천 개 URL로 퍼지는 일을 막습니다.

감사에서 배포까지의 30분 흐름

배포 후에는 URL Inspection으로 Google이 페이지를 가져오고 파싱하는지 확인합니다. 그런 다음 관련 Search Console 향상 보고서로 템플릿, 배포, 데이터 소스의 문제를 규모 있게 찾습니다. 전자는 개별 URL을, 후자는 시스템적 문제를 확인하는 데 적합합니다.

각 단계는 다른 실패를 잡습니다. 문법적으로 유효한 객체라도 페이지 사실이나 배포 검사에는 실패할 수 있습니다.

의도적으로 최소화한 기사 페이지 예시

아래 코드는 설명용이며 바로 운영에 붙이는 객체가 아닙니다. BlogPosting과 BreadcrumbList의 형태만 보여 줍니다. 제목, 설명, URL, 작성자, 날짜, 이미지는 페이지에서 확인한 실제 값을 사용하세요. 페이지에 그 사실이 없다면 객체를 더 그럴듯하게 보이게 하려고 추가하지 마세요.

이 예시에는 평점, 작성자, 게시일, 이미지, 발행자를 의도적으로 넣지 않았습니다. 이것들은 선택적 SEO 장식이 아니라 신뢰할 수 있는 출처가 필요한 주장입니다.

기술적으로 유효한 마크업도 실패하는 다섯 가지 경우

JSON 파싱은 사실 검증이 아닙니다

JSON 검증기는 문법이 파싱되는지 알려 줄 수 있습니다. 하지만 페이지에 실제 리뷰, 가격, 작성자가 있는지 또는 Product가 단순 서비스 소개 페이지인지 판단하지는 못합니다. 사실 인벤토리는 이런 실패 대부분을 초기에 잡습니다.

객체를 더 넣는다고 마크업이 좋아지지 않습니다

보이는 동영상이 있는 레시피 페이지라면 Recipe, VideoObject, 이동 경로를 정당하게 포함할 수 있습니다. 그래도 주요 목적은 명확해야 합니다. 일반 콘텐츠 페이지에 Article, Product, FAQPage, HowTo를 모두 넣으면 대개 유지 관리와 불일치 위험만 늘어납니다.

가시성과 최신성은 같은 책임자가 관리해야 합니다

Google의 일반 가이드라인은 구조화 데이터가 페이지를 대표하고 시간에 민감한 정보를 최신 상태로 유지하도록 요구합니다. 가격, 재고, 이벤트 날짜, 채용 공고, 평점을 한 번 붙여 둔 값으로 관리하면 안 됩니다. 동적 사실은 통제된 데이터 소스에 연결하고 템플릿이 바뀔 때 다시 테스트하세요.

FAQPage는 일반적인 질문 장식이 아닙니다

사용자가 실제로 볼 수 있는 질문과 답만 FAQ 마크업에 속합니다. Google 기능에는 추가 자격 요건도 있을 수 있습니다. 먼저 진짜이고 완전한 FAQ를 게시한 다음 최신 기능 가이드를 확인하세요. 결과 모양을 얻기 위해 질문 목록을 역으로 만들지 마세요.

Schema는 크롤링, 색인, 페이지 품질을 우회하지 않습니다

중요한 페이지가 noindex, 접근 제어, 크롤 규칙으로 차단되어 있다면 JSON-LD가 있어도 검색 결과 대상이 되지 않습니다. Schema는 기술 SEO의 한 계층입니다. 크롤링 가능성, 유용한 콘텐츠, 페이지 경험을 대체하지 않습니다. 사이트 전체 점검이 필요하면 Auspia SEO 도구 디렉터리 에서 적절한 감사 워크플로를 선택하세요.

게시 전 체크리스트

• [ ] 페이지의 주요 유형이 명시되어 있고 한 문장으로 근거를 설명할 수 있다.
• [ ] 모든 JSON-LD 값에 보이는 페이지 출처 또는 신뢰할 수 있는 렌더링 데이터 출처가 있다.
• [ ] 평점, 리뷰, 가격, 재고, 작성자, 날짜, 이미지, 조직 정보를 만들어 내지 않았다.
• [ ] CMS, 플러그인, 다른 구성 요소가 이미 내보낸 엔터티와 중복되지 않는다.
• [ ] JSON이 파싱되고 배포 후 렌더링된 DOM에 마크업이 존재한다.
• [ ] 대상 Google 기능의 필수 속성을 최신 공식 문서로 확인했다.
• [ ] 해당하는 경우 Rich Results Test와 Schema Markup Validator를 사용했다.
• [ ] 배포 후 URL Inspection과 Search Console 검토를 예약했다.
• [ ] 팀이 유효한 마크업은 자격과 명확성을 제공할 뿐 리치 결과나 순위를 약속하지 않는다는 점을 이해한다.

FAQ

SKILL.md가 내 사이트에 필요한 Schema를 결정할 수 있나요?

페이지 사실을 바탕으로 추천하고 미확인 항목을 찾을 수는 있지만, 사실 확인을 대신해서는 안 됩니다. 제품 가격, 리뷰, 조직 정보, 작성자, 게시일은 신뢰할 수 있는 페이지 데이터 소스나 담당자에게서 가져와야 합니다.

JSON-LD는 <head>와 <body> 중 어디에 넣어야 하나요?

Google은 HTML <head>와 <body> 모두의 JSON-LD를 지원합니다. 프레임워크나 CMS가 페이지 콘텐츠와 동기화할 수 있는 안정적인 위치를 사용하세요. 중요한 검사는 Google이 렌더링된 페이지와 일치하는 유효한 마크업을 크롤링할 수 있는지입니다.

Rich Results Test를 통과했는데 왜 아무것도 바뀌지 않았나요?

성공한 테스트는 기술적 자격 신호를 확인할 뿐 Google이 리치 결과를 표시하도록 강제하지 않습니다. Google은 쿼리, 기기, 위치, 페이지 자체를 포함한 많은 신호로 결과 표시를 선택합니다. 근거 없는 속성을 더하지 말고 콘텐츠 일치와 색인 가능성을 점검하세요.

Codex가 찾는 모든 Schema.org 속성을 채워야 하나요?

아니요. Google 문서는 불완전하거나 부정확한 속성을 많이 넣는 것보다, 적은 수라도 완전하고 정확한 권장 속성을 선호합니다. 이 제약은 일회성 프롬프트가 아니라 Skill에 넣어야 합니다.

공식 참고 자료

• Google Search Central: Introduction to structured data markup
• Google Search Central: General structured data guidelines
• Google Rich Results Test
• Schema.org

작성자: Auspia의 14-Year Technical SEO Practitioner, Julian Mercer. 크롤링 가능성, 렌더링, 구조화 데이터, 팀이 안정적으로 운영할 수 있는 기술 시스템을 다룹니다.