schema-audit

Zero-dependency CLI that crawls your site and validates its JSON-LD structured data (schema.org) the way a technical-SEO consultant would: missing required properties, malformed JSON, bad dates and prices, broken breadcrumbs — with fix hints and CI-friendly exit codes. Google retired its standalone structured-data testing workflow; this gives you a scriptable one.

Quick start

No install, no clone — just Node.js 20+:

npx schema-audit https://example.com/                          # crawl and audit
npx schema-audit --sitemap https://example.com/sitemap.xml     # audit from a sitemap

Prefer a global install? npm i -g schema-audit, then run schema-audit <url>.

Run from source instead

git clone https://github.com/madahzadeh/schema-audit.git
cd schema-audit
node schema-audit.mjs https://example.com/
npm run demo   # offline demo with seeded issues
npm test       # deterministic test suite

Example output

npx --yes schema-audit https://developer.mozilla.org --max-pages 15 --no-color

schema-audit v1.0.1

S103 no-structured-data (15)
  • https://developer.mozilla.org/en-US/
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Global_attributes
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML/Reference
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/HTML/Guides/Responsive_images
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
…
  • https://developer.mozilla.org/en-US/docs/Web/XML
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/CSS
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page
  • https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties
    no JSON-LD structured data found on this page
    fix: add a <script type="application/ld+json"> block describing the page

Summary
  pages scanned: 15   pages with JSON-LD: 0   entities: 0
  errors: 0   warnings: 15

What it checks

Code	Check	Meaning
S001	invalid-json	a ld+json block fails to parse
S002	missing-type	top-level object has no @type
S003	missing-context	no schema.org @context
S004	missing-required	required property absent for the entity type
S005	bad-value	non-ISO dates, prices with currency symbols, relative URLs, non-integer breadcrumb positions
S101	missing-recommended	recommended properties absent (richer results)
S102	duplicate-entity	the same entity declared twice on one page
S103	no-structured-data	page has no JSON-LD at all
S104	breadcrumb-order	breadcrumb positions not sequential from 1

Type rules cover the common rich-result types, based on schema.org and Google's rich-results guidance: Article / NewsArticle / BlogPosting, Product (offers, price, priceCurrency logic), LocalBusiness, Organization, Person, Event, JobPosting, Recipe, FAQPage (question/answer completeness), BreadcrumbList (positions and names), WebSite, WebPage. @graph and nested entities are fully traversed.

CLI options

Option	Default	Description
--sitemap <url>	—	audit pages listed in a sitemap (sitemap-index supported)
--urls <file>	—	audit an explicit list of URLs (one per line)
--max-pages <n>	200	crawl limit
--concurrency <n>	5	parallel requests
--timeout <ms>	10000	per-request timeout
--user-agent <ua>	schema-audit/1.0	custom User-Agent
--fail-on <level>	error	error | warning | none — controls exit code
--json	—	machine-readable JSON report
--no-color	—	disable colored output

Exit codes: 0 clean · 1 findings at/above --fail-on · 2 usage/runtime error.

CI example

name: SEO checks
on: [push]

jobs:
  schema:
    runs-on: ubuntu-latest
    steps:
      - uses: madahzadeh/schema-audit@v1
        with:
          url: https://example.com
          max-pages: '300'
          fail-on: error

Limitations

Honest scope: only JSON-LD is audited — Microdata and RDFa are not parsed. HTML is read as served (no JavaScript rendering). Required/recommended property sets are an opinionated distillation of schema.org and Google's guidance, not a certification; Google's own Rich Results Test remains the final word for eligibility.

Related tools

• hreflang-audit — international SEO: hreflang return links, invalid locale codes, canonical conflicts
• llms-txt-audit — generates and validates llms.txt so AI answer engines can read and cite your site

Hire me

I build AI automation, release workflows, mobile products, and technical-SEO-driven web systems for founders and international businesses.

• Upwork: madahzadeh.com/upwork
• Portfolio and contact: github.com/madahzadeh · iequity.co