From 35f155fa9049eba48c4326f4ce3e9ad76b3511a6 Mon Sep 17 00:00:00 2001 From: Andrew Yim Date: Wed, 27 May 2026 22:04:00 +0900 Subject: [PATCH] Upgrade Schema Validator --- .../16-seo-schema-validator/SKILL.md | 100 ++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 custom-skills/16-seo-schema-validator/SKILL.md diff --git a/custom-skills/16-seo-schema-validator/SKILL.md b/custom-skills/16-seo-schema-validator/SKILL.md new file mode 100644 index 0000000..7d350a1 --- /dev/null +++ b/custom-skills/16-seo-schema-validator/SKILL.md @@ -0,0 +1,100 @@ +--- +name: 16-seo-schema-validator +description: | + Validates an AUTHORED JSON-LD schema dataset (pre-deployment QA) and audits + live structured data (post-deployment). Runs a 5-layer offline validation + pipeline (coverage, syntax, vocabulary, Google rich-result requirements, + business-logic/consistency) and emits a severity-ranked defect log, a gate + decision, and a Markdown report. Fills the "16-seo-schema-validator" slot + referenced by seo-comprehensive-audit. + Triggers: schema validation, JSON-LD QA, structured data check, schema 검수, + 스키마 유효성 검증, 구조화 데이터 검토, rich result eligibility, schema 오류 점검. +version: "1.0" +author: OurDigital / D.intelligence +environment: Code +--- + +# SEO Schema Validator (16) + +Quality-assure structured data at scale. Built for the kind of failure where a +client review of hundreds of authored entries surfaces "too many errors" — by +moving the cheap, machine-checkable errors OUT of the human review and INTO an +automated gate that runs first. + +## Two modes + +| Mode | When | Input | Adds | +|------|------|-------|------| +| **A — Dataset QA (default)** | Before deployment, while authoring/reviewing | An authored dataset: `.xlsx` / `.csv` (one row per entry, a JSON-LD column), `.jsonl`, `.json`, or a directory of `.json/.jsonld` | Layer 0 coverage vs the canonical URL list | +| **B — Live audit** | After deployment, or feeding `seo-comprehensive-audit` | Live URLs (extract embedded JSON-LD first, then validate) | Layer 5 rendering-reality (schema present in rendered HTML, matches content) | + +This skill's primary job is **Mode A**: catch errors before the client sees them. + +## The 5 validation layers + +| # | Layer | Catches | Default severity | +|---|-------|---------|------------------| +| L0 | Coverage | URLs with no entry; entries whose URL isn't in the inventory | P1 / P2 | +| L1 | Syntax | invalid JSON, missing/wrong `@context`, no `@type`, encoding corruption | P0 / P1 | +| L2 | Vocabulary | unknown type, property not valid for type, bad value formats (URL/date/lang/currency/number) | P1 / P2 | +| L3 | Rich-result | Google **required** missing (blocks rich result); recommended absent | P0 / P2 | +| L4 | Consistency | NAP mismatch across a property, `@id` dupes/dangling refs, swapped geo, placeholder text, duplicate descriptions | P0 / P1 | + +Full rationale and the type→requirement matrix: `references/validation-methodology.md`. +Severity + category codes: `references/defect-taxonomy.md`. +Shilla page-type → schema-type map: `references/shilla-type-map.md`. +Client-facing report + P1 decision log: `templates/client-qa-report-template.md`, `templates/decision-log.md`. + +## Stage gates (aligned to the project lifecycle 설계→개발→테스트→안정화→런칭 후) + +- **G1 설계** — Lock the schema spec and the page-type→type map (`shilla-type-map.md`). Approve the entry template. *DoD:* every page template has an assigned schema type and a required-property list. +- **G2 개발** — Authors produce entries. Run the validator with `--strict`. *DoD (gate):* **zero P0**, JSON parses for 100% of entries. Entries failing this NEVER reach client review. +- **G3 테스트** — Re-run; triage P1 in `defect_log.csv` (assign owner/status). Client reviews ONLY the clean, P0-free entries, against a defect report — not raw JSON. *DoD:* P1 triaged, decisions logged in `templates/decision-log.md`. +- **G4 안정화** — Fix → re-run → confirm no regressions. Spot-check a sample in Google Rich Results Test (online, outside this runtime). *DoD:* P0=0, P1 accepted/closed, online validator green on sample. +- **G5 런칭 후** — Mode B live audit + GSC "Rich results" report monitoring. *DoD:* deployed schema matches authored dataset; no new GSC structured-data errors. + +## How to run + +```bash +# Mode A — validate an authored dataset (the common case) +python scripts/validate_schema.py path/to/schema_dataset.xlsx \ + --url-list path/to/URLlist.xlsx \ + --out schema_qa_out + +# Highest signal for the pre-review gate (unexpected props -> P1, drop optional recommended) +python scripts/validate_schema.py dataset.csv --strict --no-recommended --out qa_strict + +# Try it on the bundled flawed fixture first +python scripts/make_sample.py +python scripts/validate_schema.py fixtures/sample_schema.csv --out demo_out +``` + +**Input expectations (Mode A tabular):** the loader auto-detects a JSON-LD column +(`jsonld`, `schema`, `structured_data`, `스키마`, …) plus optional `url`/`메뉴 URL`, +`lang`/`언어코드`, `device`/`PC/MOBILE`, `page_type` columns. Multi-sheet `.xlsx` +is supported (each sheet with a JSON-LD column is read). No JSON-LD column → clear error. + +## Reading the output + +- `report.md` — counts, **gate decision (PASS = zero P0)**, defects-by-category, top P0 entries, next step. +- `defect_log.csv` — one row per finding with `status/owner/note` columns ready for triage. This is the client-facing artifact (open issues, not raw schema). +- `results.json` — full machine-readable results for dashboards / CI. + +**The rule:** an entry advances to client review only when it has **zero P0**. P1 = +triage backlog (fix before launch). P2 = optimization backlog (recommended props, style). + +## Limits & honesty + +- Offline by design — the runtime can't reach schema.org or Google. The bundled + rule set (`scripts/schema_rules.json`) is a curated hotel-focused subset; unknown + types/properties degrade to warnings (never hard errors) to avoid false positives. +- Authoritative rich-result eligibility still requires Google's online testers on a + sample at G4. This skill makes that sample small and clean, not redundant. +- Adding a new schema type or tightening a rule = edit `schema_rules.json` only. + +## Integration + +`seo-comprehensive-audit` calls this skill as pipeline stage 4 ("Schema Validation"). +For that orchestrator, run **Mode B** on a sample of live URLs and return the score +(100 − weighted defect penalty) and the issue list. For day-to-day client work, run +**Mode A** on the authored dataset.