# Validation Methodology

The reasoning behind the 5 layers, and the type → requirement matrix the validator
enforces. The matrix is the human-readable mirror of `scripts/schema_rules.json` —
if you change one, change the other.

## Why a machine gate before human review

At a few dozen entries, a person can eyeball JSON-LD. At hundreds (a multi-language,
multi-device, multi-property hotel site easily reaches 2,000+ URLs), eyeballing
fails in a predictable way: the reviewer drowns in *mechanical* errors (a missing
required field, a bad date format, a typo'd URL) and never reaches the *judgement*
errors that actually need a human (is this the right schema type for this page? is
this description accurate?).

The fix is not "review harder." It is to split the work by who is best at it:

| Error class | Best checker | This skill |
|---|---|---|
| Mechanical (parse, required-present, value format, duplicate, consistency) | A script, every time | Layers 0–4, automated |
| Judgement (type choice, copy accuracy, intent) | A human, once | Client reviews only P0-free entries |

So the gate runs first. **An entry reaches client review only when it has zero P0.**
The client then reviews a clean set against a defect report — never raw JSON in a meeting.

## The layers, in order

Each layer assumes the previous one passed for that entry. A fatal L1 failure
(unparseable JSON, no `@type`) stops deeper layers for that entry — there is nothing
to inspect.

### L0 — Coverage (needs `--url-list`)
Compares the canonical URL inventory against the URLs that actually have an entry.
- `COVERAGE_MISSING` (P1): inventory URL with no authored entry — a gap to fill.
- `COVERAGE_ORPHAN` (P2): entry whose URL isn't in the inventory — a typo, a stale
  path, or a list that's out of date. (Expect many orphans if your inventory is a
  subset; expect ~zero when it's the real canonical list.)

### L1 — Syntax
The cheapest, hardest blockers. If these fail, nothing downstream is trustworthy.
- `INVALID_JSON` (P0), `NO_SCHEMA_IN_HTML` (P0, live mode).
- `MISSING_CONTEXT` / `WRONG_CONTEXT` / `NO_TYPE` / `ENCODING_CORRUPTION` (P1).

### L2 — Vocabulary & value formats
Is the type known, and are values well-formed?
- `UNKNOWN_TYPE` (P2; P1 in `--strict`): type isn't in the curated rule set. A
  *warning*, not an error — add it to `schema_rules.json` if it's intended.
- `BAD_URL` / `BAD_DATE` / `BAD_LANG` / `BAD_CURRENCY` / `BAD_NUMBER` (P2; P1 strict).
- `UNEXPECTED_PROPERTY` (P1, `--strict` only): a property not known for a known type.
  **Off by default** — flagging every unexpected property offline produces exactly the
  false-positive flood that makes reviewers distrust the tool.

### L3 — Rich-result requirements
The contract Google enforces for eligibility.
- `MISSING_REQUIRED` (P0): a required property is absent → the rich result is blocked.
- `MISSING_RECOMMENDED` (P2): recommended properties absent. **Aggregated to one line
  per node** (never one defect per property) — this is the single most important
  noise-control decision in the tool.

### L4 — Consistency (cross-node / cross-entry)
The errors a per-entry check can't see.
- `PLACEHOLDER_TEXT` (P0): boilerplate that escaped authoring (`예시`, `수정필요`,
  `lorem`, `{{`, …). Almost always a real, embarrassing leak.
- `NAP_PHONE_MISMATCH` / `NAP_ADDRESS_MISMATCH` (P0): the same business shows
  different Name/Address/Phone across entries — a local-SEO and trust problem.
- `DUPLICATE_ID` (P1): one `@id` defined twice with different content.
- `DANGLING_ID` (P1): a `{"@id": …}` reference points at a node never defined.
- `GEO_SWAPPED` / `GEO_OUT_OF_RANGE` (P1): latitude/longitude transposed or impossible.
- `DUPLICATE_DESCRIPTION` (P1): the same description reused across ≥3 entries.

## Severity → gate

| Severity | Meaning | Gate effect |
|---|---|---|
| **P0** | Blocker. Breaks parsing, blocks the rich result, or publishes wrong data. | **Fails the gate.** Process exits 1. Entry must not reach client review. |
| **P1** | Fix before launch. Real defect, doesn't block the rich result. | Triage backlog. |
| **P2** | Optimization. Recommended props, style, orphan URLs. | Optimization backlog. |

Full code list: `defect-taxonomy.md`.

## Type → requirement matrix (mirror of `schema_rules.json`)

`required` missing → **P0**. `recommended` missing → **P2** (aggregated). Anything in
`allowed` is accepted silently. Properties outside all three are flagged only in `--strict`.

| Type | Required (P0 if missing) | Recommended (P2 if missing) |
|---|---|---|
| Organization | name, url | logo, sameAs, contactPoint, address |
| WebSite | name, url | publisher, potentialAction, inLanguage |
| WebPage | name | url, isPartOf, primaryImageOfPage, breadcrumb, datePublished, dateModified |
| Hotel / LodgingBusiness / Resort | name, address | telephone, image, priceRange, geo, url, starRating, aggregateRating |
| LocalBusiness | name, address | telephone, openingHoursSpecification, geo, image, url, priceRange, aggregateRating |
| Restaurant / FoodEstablishment | name, address | servesCuisine, priceRange, telephone, menu, openingHoursSpecification |
| FAQPage | mainEntity | — |
| Question | name, acceptedAnswer | — |
| Answer | text | — |
| BreadcrumbList / ItemList | itemListElement | — |
| ListItem | position | item, name |
| Product | name | image, offers, brand, aggregateRating, review, description, sku |
| Offer | price, priceCurrency | availability, url, validFrom, priceValidUntil |
| Article / NewsArticle / BlogPosting | headline | author, datePublished, image, dateModified, publisher |
| Event | name, startDate, location | endDate, offers, performer, image, eventStatus, eventAttendanceMode, organizer |
| Review | reviewRating, author | datePublished, reviewBody, itemReviewed |
| AggregateRating | ratingValue | reviewCount, ratingCount, bestRating |
| MemberProgram | name | hasTiers, hostingOrganization, url |

**Container types** (validated for value formats, but *not* for required/recommended,
because they only ever appear nested): PostalAddress, GeoCoordinates, ImageObject,
ContactPoint, OpeningHoursSpecification, Rating, Brand, EntryPoint, Place, OfferCatalog,
ReserveAction, MeetingRoom, Room/HotelRoom/Suite, MemberProgramTier, Menu/MenuItem, … (full
list in `schema_rules.json` → `container_types`).

## Extending the rules

Add a type, tighten a requirement, or recognize a new container by editing
`scripts/schema_rules.json` **only** — no Python change needed:
- New rich-result type → add to `known_types` with `required` / `recommended` / `allowed`.
- New nested type to stop "unknown type" warnings → add to `container_types`.
- New value-format property → add to the relevant `value_formats` group.
- New placeholder token to catch → add to `placeholder_tokens`.

After any edit, re-run `make_sample.py` + `validate_schema.py` against the fixture to
confirm you didn't regress.