Schema markup audit

1---
2name: schema-audit
3description: Audit a site's structured data one page type at a time - what is
4  there, what is wrong, what is missing - and write the JSON-LD that fixes it.
5  Use before a launch, after a migration, or when rich results disappeared.
6---
7
8# Schema markup audit
9
10Structured data is the part of a page written for machines: a block of JSON
11saying "this is an article, published on this date, by this person". Search
12engines and assistants read it to decide what a page is. This checks what a
13site currently says about itself, then writes what it should say.
14
15## 1. Pick one URL per page type, not every URL
16
17A site with 400 pages has maybe six page types: home, listing, entry, article,
18author, contact. Structured data comes out of a template, so a fault on one
19product page is a fault on all of them.
20
21List the types first, pick one live URL for each, and say in the report which
22URL stands for which type. If a type has two shapes (an article with a video,
23an article without), that is two URLs.
24
25## 2. Read what is actually there
26
27For each URL, load the page in a browser and pull:
28
29- every JSON-LD block, parsed, plus any microdata or RDFa left in the markup
30- the type of each node and the id links between them
31- whether the blocks form one connected graph or several islands that never
32  refer to each other
33
34Render the page before reading it. Structured data that only exists after
35hydration is data a crawler may never see, and that is itself a finding worth
36reporting.
37
38## 3. Check each block against the page
39
40Three questions per block, in this order:
41
421. Does the type match what the page is? An About page marked up as an Article
43   is a wrong answer, not a partial one.
442. Does every claim in the markup appear on the page? A rating nobody can see,
45   a price the page does not show, an author with no byline. This is the fault
46   that earns manual actions, and it is the most common one.
473. Are the required properties present, and the recommended ones the page
48   already has the material for?
49
50## 4. Report the faults with the reason
51
52Per page type, worst first, in this order: wrong type, invented claim, missing
53required property, missing recommended property, no markup at all.
54
55Give each fault a sentence a non-specialist can act on. "Article needs
56dateModified" is not a reason. "Without dateModified, a post you rewrote last
57week still competes on the date it was first published" is.
58
59## 5. Write the fix
60
61Output JSON-LD per page type, not per page, with the variable parts marked so
62it drops into the template.
63
64- one connected graph per page: Organization and WebSite declared once with
65  stable ids, everything below referring to them
66- author as a reference to a Person id, never a bare string
67- every URL absolute, every date ISO 8601, every id resolvable in the graph
68
69Never propose Review or AggregateRating unless real ratings exist and a visitor
70can see them on the page. Marking up ratings you do not have is the fastest way
71to lose rich results altogether.
72
73Validate the output before handing it over, and say what you validated it with.
74