Schema는 유효하지만 게시 준비가 안 된 경우: SKU.md 전달 오류 10가지

Schema를 통과한 문서도 게시 단계에서 실패할 수 있습니다. 로컬 파서가 확인할 수 없는 HTTP, 식별, 본문, 링크, 버전, 문서 그래프 계약이 남아 있기 때문입니다.

SKU.md는 판매자가 직접 호스팅하는 상품 탐색 및 안정적인 상품 지식 계층입니다. Agent가 상품을 찾고, 출처가 있는 사실을 이해하며, 실시간 상거래 정보를 어디에서 다시 확인해야 하는지 알도록 돕습니다. 새로운 Checkout 프로토콜이 아닙니다.

전달 오류 열 가지

#	오류	결정적 검사
1	잘못된 상태	정확한 HTTP 200 요구
2	리디렉션됨	리디렉션을 끄고 요청 URL을 그대로 요구
3	잘못된 MIME	text/markdown 요구; 지원되는 MIME 매개변수는 생략 가능하나 포함하면 유효해야 함
4	성공으로 위장한 대체 응답	성공으로 돌아온 일반 HTML이나 홈 페이지 바이트열 거부
5	잘못되거나 누락된 표준 URL	프런트매터 canonical과 요청 URL 비교
6	본문·파생 콘텐츠 불일치	승인 바이트열과 본문·프런트매터 일치 비교
7	깨진 링크	반드시 확인해야 하는 링크 리소스를 안전하게 가져오기
8	깨진 상위 문서 연결·탐색	/sku.md부터 순회하고 parent 관계 검증
9	잘못된 버전	의도한 sku.md/0.10-draft 계약과 Schema 요구
10	온라인 검증 생략	offline_document뿐 아니라 published_resource, document_graph 실행

오류는 정확히 열 부류입니다. 시간 초과, 리디렉션 횟수, 최대 바이트 수, 사설 네트워크 차단, 순회 깊이 같은 보안 제한은 검사를 안전하게 실행하는 방법이며, 부류를 합치거나 생략할 이유가 아닙니다.

문제 해결 흐름

1. 리디렉션 없이 정확한 URL을 요청하고 200이 아니면 전송 단계에서 중단합니다.
2. Content-Type을 확인하고 HTML 대체 응답과 잘못된 UTF-8을 거부합니다.
3. 안전한 프런트매터를 파싱한 뒤 표준 URL, 언어, 문서 유형, 버전을 비교합니다.
4. 게시 응답을 승인 바이트열 및 파생 본문과 비교해 무결성을 확인합니다.
5. 허용 범위 안의 동일 오리진 링크를 따라 parent, 표준 URL, 탐색 경로를 검증합니다.
6. 온라인 검사 보고서를 저장하고 경로, CDN, 게시 변경 후 다시 실행합니다.

전송 계층 오류를 문서 Schema 규칙을 느슨하게 만들어 고치지 마세요. 실패한 계층을 수정해야 합니다.

일반적인 로컬 검사가 놓치는 이유

편집자는 HTTP 요청 없이 YAML과 JSON Schema를 검증할 수 있습니다. 정적 빌드가 올바른 바이트열을 생성해도 운영 /sku.md가 HTTP 200을 반환하는 브랜드 404 페이지로 이어질 수 있습니다. 브라우저는 301 응답을 보여 주지 않은 채 따라가고, CDN은 저장소의 새 파일 대신 오래된 승인 파일을 제공할 수 있습니다.

로컬 신호	숨은 온라인 위험
Schema 통과	잘못된 URL, 상태, MIME, 표준 URL
읽기 좋게 보임	리디렉션 또는 HTML 호환 보기
상품 URL 하나 작동	깨진 루트 상위 문서 또는 동일 계층 문서 그래프
배포 완료	캐시되거나 변환된 바이트열

마지막 유효 버전을 잃지 않고 수정하기

게시 전 생성·검증하고 승인 바이트열을 원자적으로 교체합니다. 새 문서나 경로가 실패하면 마지막으로 확인한 유효 리소스를 유지합니다. 알 수 없는 리소스는 성공으로 위장한 대체 응답이 아닌 정확한 404를 반환해야 합니다. v0.10 적합성 범위는 오프라인 문서, 공개 리소스, 문서 그래프의 근거를 분리해 부분 결과를 완료로 표시하지 못하게 합니다.

더 읽기

전체 흐름은 첫 SKU.md 게시하기에서, 오퍼 매핑 전 분류는 안정적인 지식과 라이브 데이터에서 확인하세요.

다음 단계

적합성 테스트 실행하기