Schema.org structured data audit and generation optimized for AI discoverability — detect, validate, and generate JSON-LD markup
Structured data is the primary machine-readable signal that tells AI systems what an entity IS, what it does, and how it connects to other entities. While schema markup has traditionally been about earning Google rich results, its role in GEO is fundamentally different: structured data is how AI models understand and trust your entity. A complete entity graph in structured data dramatically increases citation probability across all AI search platforms.
fetch_page.py (see note below)IMPORTANT: WebFetch converts HTML to markdown and strips <head> content, which removes JSON-LD blocks. Use fetch_page.py instead:
python3 ~/.claude/skills/geo/scripts/fetch_page.py <url> page
The output includes a structured_data array with all parsed JSON-LD blocks from the page.
Look for <script type="application/ld+json"> blocks in the HTML. Parse each block as JSON. A page may contain multiple JSON-LD blocks — collect all of them.
Look for elements with itemscope, itemtype, and itemprop attributes. Map the hierarchy of nested items. Note: Microdata is harder for AI crawlers to parse than JSON-LD. Flag a recommendation to migrate to JSON-LD if Microdata is the only format found.
Look for elements with typeof, property, and vocab attributes. Similar to Microdata — recommend migration to JSON-LD.
JSON-LD is the strongly recommended format for GEO. Google, Bing, and AI platforms all process JSON-LD most reliably. If the site uses Microdata or RDFa exclusively, flag this as a high-priority migration.
For each detected schema block, validate:
@type match a recognized Schema.org type? Check against https://schema.org/docs/full.html.sameAs properties linking to other platform presences?Essential for entity recognition across all AI platforms. This is how AI models identify WHAT the business is.
Required properties:
@type: "Organization" (or subtype: Corporation, LocalBusiness, etc.)name: Official business nameurl: Official website URLlogo: URL to logo image (ImageObject preferred)Recommended properties for GEO:
sameAs: Array of ALL platform URLs (see sameAs strategy below)description: 1-2 sentence description of the organizationfoundingDate: ISO 8601 datefounder: Person schemaaddress: PostalAddress schemacontactPoint: ContactPoint with telephone, email, contactTypeareaServed: Geographic areanumberOfEmployees: QuantitativeValueindustry: Text or DefinedTermaward: Array of awards receivedknowsAbout: Array of topics the organization is expert in (strong GEO signal)Extends Organization. Critical for local AI search results and Google Gemini.
Additional required properties:
address: Full PostalAddresstelephone: Phone numberopeningHoursSpecification: Operating hoursRecommended for GEO:
geo: GeoCoordinates (latitude, longitude)priceRange: Price indicatoraggregateRating: AggregateRating schemareview: Array of Review schemashasMap: URL to Google MapsThe Author schema is one of the strongest E-E-A-T signals for AI platforms.
Article required:
@type: "Article" (or NewsArticle, BlogPosting, TechArticle)headline: Article titledatePublished: ISO 8601dateModified: ISO 8601 (critical for freshness signals)author: Person or Organization schemapublisher: Organization schema with logoimage: Representative imageAuthor (Person) required for GEO:
name: Full nameurl: Author page URL on the sitesameAs: LinkedIn, Twitter, personal site, Google Scholar, ORCIDjobTitle: Professional titleworksFor: Organization schemaknowsAbout: Array of expertise areasalumniOf: Educational institutionsaward: Professional awardsRequired:
name, description, imageoffers: Offer with price, priceCurrency, availabilitybrand: Brand schemasku or gtin/mpnRecommended for GEO:
aggregateRating: AggregateRatingreview: Array of individual reviewscategory: Product categorymaterial, weight, width, height (where applicable)Status as of 2024: Google restricts FAQ rich results to government and health sites. However, the FAQPage schema still serves GEO purposes — AI platforms parse FAQ structured data for question-answer extraction. Implement it for AI readability even though rich results may not appear.
Structure:
@type: "FAQPage"mainEntity: Array of Question schemas, each with acceptedAnswer containing an Answer schemaRequired:
name, descriptionapplicationCategory: e.g., "BusinessApplication"operatingSystem: Supported platformsoffers: PricingRecommended for GEO:
aggregateRating: User ratingsfeatureList: Array of features (strong citation signal)screenshot: ScreenshotssoftwareVersion: Current versionreleaseNotes: Link to changelogStructure:
{
"@type": "WebSite",
"name": "Site Name",
"url": "https://example.com",
"potentialAction": {
"@type": "SearchAction",
"target": {
"@type": "EntryPoint",
"urlTemplate": "https://example.com/search?q={search_term_string}"
},
"query-input": "required name=search_term_string"
}
}
Use as a standalone schema on About/Bio pages. This builds the entity graph for individual expertise.
Required: name, url
Recommended for GEO: sameAs, jobTitle, worksFor, knowsAbout, alumniOf, award, description, image
The speakable property marks specific sections of content as particularly suitable for voice and AI assistant consumption. Add to Article or WebPage schemas.
{
"@type": "Article",
"speakable": {
"@type": "SpeakableSpecification",
"cssSelector": [".article-summary", ".key-takeaway"]
}
}
This signals to AI assistants which passages are the best candidates for citation or reading aloud.
| Schema | Status | Note |
|---|---|---|
| HowTo | Rich results deprecated Aug 2023 | Still useful for AI parsing, but do not promise rich results |
| FAQPage | Restricted to govt/health Aug 2023 | Still useful for AI parsing (see above) |
| SpecialAnnouncement | Deprecated 2023 | Was for COVID; remove if still present |
| CourseInfo | Replaced by Course updates 2024 | Use updated Course schema properties |
VideoObject contentUrl | Changed behavior 2024 | Must point to actual video file, not page URL |
| Review snippet | Stricter enforcement 2024 | Self-serving reviews on product pages may not display |
Flag any deprecated schemas found and recommend replacements.
The sameAs property is the single most important structured data property for GEO. It tells AI systems: "This entity on my website is the SAME entity as these profiles elsewhere." This creates the entity graph that AI platforms use to verify, trust, and cite sources.
https://www.wikidata.org/wiki/Q12345)Based on the detected business type, generate ready-to-paste JSON-LD blocks. Always generate:
@graph pattern to include multiple schemas in one JSON-LD block@id properties for cross-referencing between schemasspeakable on Article schemas with CSS selectors pointing to key content sections<head> section — NOT injected via JavaScript{
"@context": "https://schema.org",
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Company Name",
"url": "https://example.com",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png",
"width": 600,
"height": 60
},
"description": "Concise description of what the company does.",
"foundingDate": "2020-01-15",
"founder": {
"@type": "Person",
"name": "Founder Name",
"sameAs": "https://www.linkedin.com/in/founder"
},
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main St",
"addressLocality": "City",
"addressRegion": "State",
"postalCode": "12345",
"addressCountry": "US"
},
"contactPoint": {
"@type": "ContactPoint",
"telephone": "+1-555-555-5555",
"contactType": "customer service",
"email": "[email protected]"
},
"sameAs": [
"https://en.wikipedia.org/wiki/Company_Name",
"https://www.wikidata.org/wiki/Q12345",
"https://www.linkedin.com/company/company-name",
"https://www.youtube.com/@companyname",
"https://twitter.com/companyname",
"https://github.com/companyname",
"https://www.crunchbase.com/organization/company-name"
],
"knowsAbout": [
"Topic 1",
"Topic 2",
"Topic 3"
]
}
| Criterion | Points | How to Score |
|---|---|---|
| Organization/Person schema present and complete | 15 | 15 if full, 10 if basic, 0 if none |
| sameAs links (5+ platforms) | 15 | 3 per valid sameAs link, max 15 |
| Article schema with author details | 10 | 10 if full author schema, 5 if name only, 0 if none |
| Business-type-specific schema present | 10 | 10 if complete, 5 if partial, 0 if missing |
| WebSite + SearchAction | 5 | 5 if present, 0 if not |
| BreadcrumbList on inner pages | 5 | 5 if present, 0 if not |
| JSON-LD format (not Microdata/RDFa) | 5 | 5 if JSON-LD, 3 if mixed, 0 if only Microdata/RDFa |
| Server-rendered (not JS-injected) | 10 | 10 if in HTML source, 5 if JS but in head, 0 if dynamic JS |
| speakable property on articles | 5 | 5 if present, 0 if not |
| Valid JSON + valid Schema.org types | 10 | 10 if no errors, 5 if minor issues, 0 if major errors |
| knowsAbout property on Organization/Person | 5 | 5 if present with 3+ topics, 0 if missing |
| No deprecated schemas present | 5 | 5 if clean, 0 if deprecated schemas found |
Generate GEO-SCHEMA-REPORT.md with:
# GEO Schema & Structured Data Report — [Domain]
Date: [Date]
## Schema Score: XX/100
## Detected Schemas
| Page | Schema Type | Format | Status | Issues |
|---|---|---|---|---|
| / | Organization | JSON-LD | Valid | Missing sameAs |
| /blog/post-1 | Article | JSON-LD | Valid | No author schema |
## Validation Results
[List each schema with pass/fail per property]
## Missing Recommended Schemas
[List schemas that should be present based on business type but are not]
## sameAs Audit
| Platform | URL | Status |
|---|---|---|
| Wikipedia | [URL or "Not found"] | Present/Missing |
| LinkedIn | [URL or "Not found"] | Present/Missing |
[Continue for all recommended platforms]
## Generated JSON-LD Code
[Ready-to-paste JSON-LD blocks for each missing or incomplete schema]
## Implementation Notes
- Where to place each JSON-LD block
- Server-rendering requirements
- Testing with Google Rich Results Test and Schema.org Validator