Schema Markup Audit

Schema Markup Audit

Audit the structured data (schema markup) of a website and produce an actionable SEO report.

When to use this skill

Use this skill when the user asks to:

• Audit or validate schema markup / structured data on a website
• Check rich result eligibility (e.g., Product, Article, FAQ, Review snippets)
• Find missing, invalid, or incomplete JSON-LD, Microdata, or RDFa
• Recommend which schema types to add to which pages
• Fix errors or warnings reported by Google's Rich Results Test or Search Console

Inputs to collect

Before starting, confirm with the user:

1. Site URL or local files — a live site root URL (e.g., https://example.com), a sitemap URL, a list of URLs, or a local folder of HTML files.
2. Scope — full site, a specific section (e.g., /products/), or a list of URLs.
3. Crawl limits — max pages (default 200) for live crawls.
4. Business context — site type (e-commerce, blog, local business, SaaS, etc.) so page-type-to-schema-type expectations can be set.

Workflow

Step 1: Gather the page set

• If a sitemap is available (/sitemap.xml), fetch it to get the canonical page list.
• Otherwise, crawl from the homepage following only same-host links.
• For local HTML folders, enumerate all .html files.

Step 2: Extract structured data

Use scripts/extract_schema.py to fetch pages and extract all structured data (JSON-LD, Microdata, RDFa) into a JSON inventory:

python3 scripts/extract_schema.py https://example.com --max-pages 200 --output schema_inventory.json
# already crawled once (e.g. in a full SEO audit)? skip the crawl and reuse the shared cache:
# python3 scripts/fetch_pages.py https://example.com --output page_cache.json
# python3 scripts/extract_schema.py --from-cache page_cache.json --output schema_inventory.json

For every page, record:

• Each structured data block: format (json-ld, microdata, rdfa), @type, raw parsed object
• JSON parse errors in <script type="application/ld+json"> blocks
• Page metadata: title, canonical URL, meta robots

Step 3: Run the audit checks

Use scripts/validate_schema.py to validate the inventory:

python3 scripts/validate_schema.py schema_inventory.json --output audit_report.json

Evaluate each check defined in references/audit-checks.md. The core checks are:

Step 4: Verify against external validators

When the site is live, recommend the user confirm key templates with:

• Google Rich Results Test (https://search.google.com/test/rich-results)
• Schema.org validator (https://validator.schema.org/)

Validate one representative URL per page template rather than every page.

Step 5: Produce the report

Write a report following the structure in references/report-template.md:

1. Summary — pages scanned, schema blocks found, types in use, issue counts by severity
2. Coverage map — page types vs. expected schema types, showing gaps
3. Issues — one section per failing check, listing affected page, schema type, property, and a specific fix
4. Opportunities — schema types worth adding for rich result eligibility
5. Prioritized action list — ordered by severity and estimated impact

Step 6: Recommend fixes

For each issue, give a concrete, copy-pasteable recommendation, e.g.:

• Fix the JSON syntax error in the JSON-LD block on /products/widget (trailing comma at line 14)
• Add the required offers property to the Product schema on all product pages, including price, priceCurrency, and availability
• Provide a complete corrected JSON-LD snippet for the page template, using real values from the page content

Always recommend JSON-LD as the implementation format (Google's preferred format) when adding new markup.

Optional: export the report

As a Word document (.docx)

If the user wants the report as a .docx (for example, to share with stakeholders or attach to a ticket), save the Markdown report to a file and convert it:

python3 scripts/md_to_docx.py report.md --output report.docx

scripts/md_to_docx.py uses only the Python standard library (no pip install) and renders headings, tables, lists, links, bold/italic, and code blocks. Offer this whenever a user asks for a Word doc, a .docx, or a shareable/downloadable report.

As a CSV of findings (.csv)

If the user wants the raw findings as a spreadsheet (for filtering, sorting, or triage in Sheets or Excel), convert the audit's audit_report.json directly:

python3 scripts/findings_to_csv.py audit_report.json --output findings.csv

scripts/findings_to_csv.py is also standard-library only. It writes one row per finding, with check and severity columns prepended and list fields (e.g. the pages sharing a duplicate value) joined with ; . Unlike the .docx, which reformats the written report, the CSV is a direct dump of the structured findings — offer it whenever a user wants the data itself, a spreadsheet, or to slice findings by check or severity.

Resources

• scripts/md_to_docx.py — convert the Markdown report into a Word (.docx) document (standard library only)
• scripts/findings_to_csv.py — flatten the audit findings JSON into a CSV, one row per finding (standard library only)
• references/audit-checks.md — full definitions, severities, and rationale for every audit check, plus required/recommended properties per schema type
• references/report-template.md — report output structure
• scripts/extract_schema.py — crawl pages and extract all structured data into a JSON inventory
• scripts/validate_schema.py — run audit checks against a schema inventory JSON file