AI Schema 만들기: Article·FAQ·Breadcrumb JSON-LD 자동 생성 가이드
ai schema 만들기 한 줄 요약
AI한테 “이 블로그 글의 Article 스키마 JSON-LD(JavaScript Object Notation for Linked Data) 만들어줘”라고 시키면, 형식은 거의 완벽하게 나와요. 근데 값이 틀려요. 글 제목이 아니라 엉뚱한 문장이 headline에 들어가고, description은 도입부 복붙이 되기도 해요. 그래서 핵심은 “출력 형식을 고정하고 → 사람이 값을 검증하고 → Google Rich Results Test로 최종 확인”하는 세 단계예요.
참고로 FAQPage 스키마를 넣는다고 검색 결과에 FAQ 박스가 바로 뜨진 않아요. 2026년 4월 기준 Google은 FAQ rich result 노출을 정부·건강 관련 권위 사이트로 제한하고 있어요.
플러그인이 넣어주는 스키마만 믿고 있다가 FAQ 질문이 본문이랑 안 맞고, breadcrumb 계층도 애매해서 다시 뜯어고친 적이 꽤 있었어요. Rich Results Test는 통과했는데 정작 설명문이 글 요약이 아니라 어색한 홍보 문장으로 들어간 적도 있더라고요. 그때 느낀 게 하나였어요. 구조는 자동화해도 되는데, 값은 그냥 믿으면 안 된다는 점이죠.
그래서 요즘은 브리프 → 초안 → 스키마 → 검증 → 발행 순서로 잡아요. 이 흐름을 쓰면 Article, FAQPage, BreadcrumbList 세 가지를 한 번에 맞출 수 있고, structured output JSON-LD 설정도
특히 브리프 단계에서 제목, 설명, 카테고리를 먼저 정리해두면 AI 블로그 브리프 자동 생성: 실전 파이프라인 구축기에서 만든 메타를 그대로 넘기기 좋거든요. 이 글에서는 생성 → 검증 → 자동화 순서로 정리할게요.
JSON-LD 기초와 플러그인의 한계
JSON-LD는 “이 글의 제목은 뭐고, 작성자는 누구고, 언제 썼는지”를 검색엔진이 읽을 수 있는 형식으로 HTML에 심어두는 거예요. 사람 눈에는 안 보이지만, Google이 이걸 읽고 검색 결과에 별점, FAQ 박스, 경로(breadcrumb) 같은 부가 정보를 띄워줘요. 이런 걸 리치 결과(rich result)라고 부르는데, 클릭률을 꽤 좌우하더라고요.
실제 코드는 이렇게 생겼어요. HTML <head> 안에 <script> 태그로 들어가죠.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "AI Schema 만들기 가이드",
"author": { "@type": "Person", "name": "picoax" },
"datePublished": "2026-04-12"
}
블로그에서 자주 쓰는 JSON-LD 스키마는 세 가지인데요.
| 스키마 | 역할 | 검색 결과에 뜨는 것 |
|---|---|---|
| Article | 글의 제목, 작성자, 날짜 등 기본 정보 | 뉴스·블로그 카드 형태 |
| FAQPage | 자주 묻는 질문과 답변 | FAQ 아코디언 (제한적) |
| BreadcrumbList | 홈 → 카테고리 → 글 경로 | 검색 결과 URL 대신 경로 표시 |
Yoast나 Rank Math 같은 워드프레스 SEO 플러그인을 쓰면 Article과 Breadcrumb은 자동으로 들어가요. 직접 Yoast 켜고 확인해보면 기본 Article 마크업은 꽤 잘 넣어주더라고요. 근데 FAQ 질문 텍스트, breadcrumb 계층, 글마다 달라지는 설명문은 글 본문 기준으로 다시 뽑아야 정확해지는 경우가 많아요.
이미 플러그인 켜져 있는데 왜 또 손대냐고요? 플러그인은 모든 글에 같은 틀을 씌워요. 글마다 검색 의도가 다르니까 그 틀이 안 맞을 때가 있거든요.
| 항목 | 플러그인 자동 생성 | AI 직접 생성 |
|---|---|---|
| Article 기본 필드 | 대체로 충분해요 | 글 성격에 맞게 더 세밀하게 조정 가능 |
| FAQ 질문/답변 | 본문과 어긋날 때가 있어요 | 본문 기준으로 다시 뽑기 좋아요 |
| Breadcrumb 계층 | 카테고리 구조에 묶여요 | 글 의도에 맞게 계층 점검 가능 |
| 검증 흐름 | 플러그인 내부 로직 의존 | 생성 뒤 검사 단계를 따로 둘 수 있어요 |
| 운영 난도 | 쉬움 | 세팅은 조금 더 필요해요 |
FAQPage는 특히 기대치를 잘 잡아야 해요. 스키마를 넣는 것과 Google이 FAQ rich result를 보여주는 건 다른 문제죠. 일반 블로그라면 “마크업은 넣되, 노출은 덤” 정도로 생각하는 편이 안전해요. 이건 Google FAQPage 문서 기준으로 봐도 그렇고요.
설명문도 비슷한 상황이에요. 플러그인 기본값이 나쁘진 않은데, 글의 핵심 답을 바로 보여주진 않는 경우가 많아요. 그래서 description 필드는 AI 메타 설명 만들기: 제목부터 검수까지 워크플로우에서 먼저 다듬은 문장을 다시 쓰면 결과가 안정적이었어요.
Structured Output으로 JSON-LD 생성하기
ai schema 만들기 흐름은 생각보다 단순해요. 쉽게 말하면 “AI한테 답을 받을 때, JSON 형식을 미리 정해두는 것”이에요. ChatGPT나 Claude한테 “아무렇게나 답해”라고 하면 매번 다른 형식이 나오잖아요? Structured Output은 “이 칸에 이 값만 채워”라고 틀을 고정하는 방식이고요.
프롬프트에 “JSON으로만 답해”라고 쓰는 방법도 있긴 한데, 운영 파이프라인에서는 그 방식이 오래 못 버텨요. 괄호 하나 빠지면 자동화 전체가 멈추거든요.
OpenAI는 Structured Outputs라는 공식 기능이 있고, Claude도 같은 방식을 지원해요. Python에서는 Pydantic이라는 라이브러리로 “이런 모양의 JSON만 받을게요”를 정의하면 돼요. 아래 코드를 보면 바로 이해돼요.
from pydantic import BaseModel, Field, ConfigDict
from openai import OpenAI
# JSON-LD 필드 별칭을 그대로 쓰기 위한 모델
class TechArticleSchema(BaseModel):
model_config = ConfigDict(populate_by_name=True)
context: str = Field(alias="@context")
type_name: str = Field(alias="@type")
headline: str
description: str
datePublished: str
dateModified: str
client = OpenAI()
# 글 본문을 넣고 TechArticle JSON-LD 생성
response = client.responses.parse(
model="gpt-5.4",
input=[
{"role": "system", "content": "블로그 글에서 TechArticle JSON-LD만 생성하세요."},
{"role": "user", "content": post_markdown},
],
text_format=TechArticleSchema,
)
schema = response.output_parsed.model_dump(by_alias=True)
print(schema)
{
"@context": "https://schema.org",
"@type": "TechArticle",
"headline": "AI Schema 만들기: Article·FAQ·Breadcrumb JSON-LD 자동 생성 가이드",
"description": "Article, FAQPage, BreadcrumbList를 AI로 생성하고 검증하는 실전 흐름",
"datePublished": "2026-04-12",
"dateModified": "2026-04-12"
}
위 코드에서 TechArticleSchema가 “이 모양으로만 답해”라는 틀이에요. 이렇게 틀을 정해두면 AI가 매번 같은 구조로 JSON-LD를 뱉어주죠.
FAQPage도 같은 방식으로 만들 수 있는데, 주의할 점이 있어요. 본문에 실제로 있는 질문만 뽑아야 해요. “5개 만들어줘”라고 시키면 없는 질문까지 지어내더라고요. 브리프 단계에서 질문 후보를 미리 좁혀두면 AI 브리프 생성 파이프라인와도 잘 이어져요.
여기서 함정이 하나 있어요. JSON-LD는 @context, @type 같은 특수한 키를 써요. Python 변수명에는 @를 못 쓰니까, alias 설정으로 “실제 출력할 때는 이 이름을 써”라고 알려줘야 해요. 이거 빠뜨리면 JSON-LD가 깨져요.
스키마가 맞아도 값이 틀리는 이유
여기서 많이 넘어져요. Google 검증 도구를 돌리면 초록 체크가 뜨는데, 막상 내용을 보면 엉뚱해요. 왜냐면 검증 도구는 “칸이 다 채워져 있는지”만 보지, “채워진 값이 맞는지”는 안 봐주거든요.
처음엔 저도 Rich Results Test만 통과하면 끝인 줄 알았어요. 근데 description이 본문 핵심이 아니라 도입부 한 줄만 복사되거나, breadcrumb 마지막 항목이 실제 카테고리와 다르게 붙는 일이 있더라고요. FAQ도 마찬가지예요.
그래서 ai schema 만들기 과정에 검증 레이어를 따로 둬야 해요. AI로 스키마를 만들 때 이 단계가 빠지면 오히려 더 위험해지는 셈이죠.
- Article
headline이 H1과 정확히 일치하는지 확인 description이 첫 문단 복붙이 아니라 핵심 답을 담고 있는지 체크- FAQ 질문/답변이 본문에 실제로 존재하는지 대조
- Breadcrumb 계층이 실제 카테고리 구조와 맞는지 점검
datePublished,dateModified가 프론트매터와 맞는지 보기- 검증 도구 통과 뒤 사람이 한 번 더 읽기
FAQ 후보를 뽑을 때는 실제 검색어가 있는 질문만 남기는 편이 나아요. 그런 점에서 Search Console 키워드 분석: 데이터에서 글감 뽑는 5단계 워크플로우에서 정리한 질문 데이터와 같이 보는 흐름이 꽤 잘 맞아요.
팁이 하나 있어요. 스키마를 설계할 때 AI한테 “먼저 이유를 설명하고, 그다음에 최종 값을 채워”라고 순서를 정해주면 결과가 더 정확해져요. 반대로 “답부터 내고 이유는 나중에”라고 하면 description이 도입부 복붙으로 빠지는 비율이 확 올라갔거든요.
직접 ai schema 만들기 파이프라인을 돌려보면 가장 자주 틀리는 필드가 바로 이 description이에요. headline은 제목을 그대로 가져가니까 거의 맞는데, description은 “글의 핵심 한 줄”이 아니라 첫 문단을 그냥 복사하는 경우가 절반이 넘었고요. 두 번째로 자주 어긋나는 건 FAQ 질문이죠. 본문에 없는 질문을 그럴듯하게 지어내는 건 structured output으로도 못 막더라고요.
블로그 스키마 마크업 자동화 파이프라인 넣기
이 순서를 몇 달 돌려봤는데, 스키마를 발행 직전에 급하게 만들면 자꾸 빠지는 게 생겨요. 글 쓰기 전에 제목, 카테고리, 설명 같은 값을 미리 정리해두고, 발행 직전에 스키마만 한 번 찍어내는 구조가 훨씬 편하더라고요.
설마 발행 직전에 JSON-LD 세 덩어리를 손으로 붙이고 있진 않죠? 그 방식은 한두 편까진 괜찮은데, 글이 쌓이면 바로 .
아래처럼 research → brief → draft → schema → validate → publish 순서로 고정해두면 돼요.
# 1) 글 메타 정리
./brief.sh --topic "ai schema 만들기" --format markdown
# 2) 초안에서 스키마 입력값 추출
python pipeline/extract_post_meta.py --input draft.md --output post_meta.json
# 3) Article, FAQ, Breadcrumb JSON-LD 생성
python pipeline/generate_schema.py --input post_meta.json --types article,faq,breadcrumb
# 4) 검증용 HTML 렌더링
python pipeline/render_schema_preview.py --input schema/ --output preview/schema-test.html
# 5) Rich Results 검사
open preview/schema-test.html
출력 예시:
- schema/article.jsonld 생성
- schema/faq.jsonld 생성
- schema/breadcrumb.jsonld 생성
- preview/schema-test.html 생성
OpenAI나 Claude의 공식 기능만 써도 되는데, 좀 더 편하게 감싸주는 도구도 있어요. Instructor(인스트럭터)라는 오픈소스 라이브러리인데, “JSON 형식이 깨지면 자동으로 다시 물어보기”, “OpenAI랑 Claude를 같은 코드로 바꿔 쓰기” 같은 기능이 있어요.
내부 링크도 같은 단계에서 같이 다루면 흐름이 깔끔해져서 블로그 내부링크 자동화: 규모별 도구 비교와 검수 워크플로우와 묶어 운영하기 좋아요.
| 항목 | OpenAI | Claude | Instructor |
|---|---|---|---|
| 뭐하는 건지 | API에 내장된 구조화 출력 | API에 내장된 구조화 출력 | 구조화 출력을 감싸주는 오픈소스 |
| 대표 가격 | gpt-5.4 기준 입력 $2.50 / 출력 $15.00 per 1M | Sonnet 4.6 기준 입력 $3 / 출력 $15 per 1M | 무료 (연결한 AI 모델 요금만 나감) |
| 이런 팀에 맞아요 | OpenAI만 쓰는 팀 | Claude나 AWS Bedrock도 같이 쓰는 팀 | 자동 재시도가 필요하거나 여러 AI를 섞어 쓰는 팀 |
OpenAI는 공식 가이드가 잘 되어 있어서 처음 시작하기 좋고, Claude는 쓸 수 있는 환경이 넓어서 멀티 플랫폼에 유리해요. Instructor는 “형식이 깨지면 자동으로 다시 물어봐주는” 기능이 편하더라고요.
위 가격은 2026년 4월 기준이에요. 블로그 글 하나에 스키마 3개 만드는 정도면 비용은 거의 안 들죠.
세 도구를 직접 써보니 가장 손이 덜 가는 조합은 “Pydantic + OpenAI”였어요. 설정이 단순하고, 공식 예제를 그대로 복붙해서 쓸 수 있죠. Claude는 AWS Bedrock 같은 다른 환경도 같이 쓸 때 유리하고, Instructor는 여러 AI를 섞어 쓰거나 자동 재시도가 중요한 팀에 잘 맞았어요.
자주 묻는 질문
ai schema 만들기 관련 질문은 비슷하게 모여요. 실제로 막히는 지점만 추렸어요.
Q1: JSON 스키마로 AI 출력을 100% 보장할 수 있나요?
A: 형식은 거의 보장할 수 있어요. 근데 의미까지 보장되진 않아요. headline, description, breadcrumb 값이 실제 글과 맞는지는 따로 봐야 해요.
Q2: Structured Output을 쓰면 응답 품질이 떨어지나요?
A: 스키마 설계가 나쁘면 그렇게 느껴질 수 있어요. “이유를 먼저 설명하고 → 최종 값을 채워”라는 순서로 칸을 배치하면 출력이 더 단단해져요. 더 까다로운 작업이면 AI한테 일단 자유롭게 답하게 한 뒤, 두 번째 호출에서 형식만 맞추는 방법도 괜찮고요.
Q3: SEO 플러그인이 있는데 왜 직접 만들죠?
A: 기본 Article 정도는 플러그인도 충분해요. 근데 글 본문 기준 FAQ, breadcrumb 계층, 설명문 품질까지 맞추려면 직접 생성이 더 정확할 때가 많더라고요. 메타 설명 쪽은 AI 메타 설명 만들기: 제목부터 검수까지 워크플로우와 묶어서 보는 게 편해요.
Q4: FAQPage 넣으면 Google FAQ 박스가 바로 뜨나요?
A: 그 기대는 낮추세요. 2026년 4월 12일 기준 Google 공식 문서는 FAQ rich result 노출을 정부·건강 중심 권위 사이트에 제한하고 있어요. 그래도 FAQPage 자체는 검색엔진 문맥 전달, 내부 품질 관리, 다른 소비 환경 대비용으로는 남길 만해요.
Q5: 프롬프트만으로 JSON 받으면 안 되나요?
A: 프로토타입까진 괜찮아요. 운영 파이프라인이면 안 맞아요. 한 번씩 괄호가 깨지거나 필드가 빠지는 순간 자동화 전체가 멈추거든요.
다음 단계
ai schema 만들기가 처음이라면, 오늘은 Article 하나만 먼저 자동 생성해서 Rich Results Test에 넣어보세요. 그다음 description까지 같이 묶고 싶으면 AI 메타 설명 만들기: 제목부터 검수까지 워크플로우로 이어가면 흐름이 바로 붙어요. 안 되면 댓글에 실패한 JSON-LD 한 조각만 남겨주세요. 어디서 깨졌는지 금방 좁혀볼 수 있어요.
