Developer ToolsIntermediate
GEO Schema: Structured Data for AI Citation
Audit and generate schema.org JSON-LD built for AI comprehension, with a sameAs entity graph, knowsAbout topics, and a 0-100 scoring rubric
#geo#schema#json-ld#structured-data#seo
ChatGPT and Perplexity decide whether to cite you based on whether they can tell what your business actually is. Rich results are a side effect. This playbook treats JSON-LD as the entity graph AI models read to verify and trust a source.
Who it's for: GEO consultants, technical SEOs, SaaS marketing engineers, agency owners running client audits, publishers optimizing author E-E-A-T, developers shipping schema on Next.js and WordPress sites
Example
"Audit the structured data on stripe.com and generate what's missing" → A schema score out of 100, a table of every detected JSON-LD block with validation errors, a sameAs audit across Wikipedia, Wikidata, LinkedIn, and Crunchbase, plus ready-to-paste Organization and WebSite blocks
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
# GEO Schema & Structured Data
Audit, validate, and generate schema.org JSON-LD markup optimized for AI discoverability. 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.
Schema markup has traditionally been about earning Google rich results. Its role in GEO is different: structured data is how AI models understand and trust your entity. A complete entity graph in structured data increases citation probability across AI search platforms.
## How to Use This
1. Fetch the target page HTML
2. Detect all existing structured data (JSON-LD, Microdata, RDFa)
3. Validate detected schemas against Schema.org specifications
4. Identify missing recommended schemas based on business type
5. Generate ready-to-use JSON-LD code blocks
6. Output GEO-SCHEMA-REPORT.md
---
## Step 1: Detection
**Fetching caveat:** WebFetch converts HTML to markdown and strips `<head>` content, which removes JSON-LD blocks. Retrieve the raw HTML instead — `curl -sL <url>` from Bash works, or use a fetch script that returns unmodified source. The full geo-seo-claude toolkit ships a `fetch_page.py` helper whose output includes a `structured_data` array with all parsed JSON-LD blocks; if you have the suite installed, use that.
### Scan for JSON-LD
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.
### Scan for Microdata
Look for elements with `itemscope`, `itemtype`, and `itemprop` attributes. Map the hierarchy of nested items. 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.
### Scan for RDFa
Look for elements with `typeof`, `property`, and `vocab` attributes. Similar to Microdata — recommend migration to JSON-LD.
### Priority Order
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.
---
## Step 2: Validation
For each detected schema block, validate:
1. **Valid JSON**: Is the JSON-LD syntactically valid? Check for trailing commas, unquoted keys, malformed strings.
2. **Valid @type**: Does the `@type` match a recognized Schema.org type? Check against https://schema.org/docs/full.html.
3. **Required Properties**: Does the schema include all required properties for its type? (See per-type requirements below.)
4. **Recommended Properties**: Does the schema include recommended properties that increase AI discoverability?
5. **sameAs Links**: Does the schema include `sameAs` properties linking to other platform presences?
6. **URL Validity**: Do all URLs in the schema resolve (not 404)?
7. **Nesting**: Is the schema properly nested (e.g., author inside Article, address inside Organization)?
8. **Rendering Method**: Is the JSON-LD in the server-rendered HTML or injected via JavaScript? Per Google's December 2025 guidance, JavaScript-injected structured data may face delayed processing. Flag any schema that requires JS execution.
---
## Step 3: Schema Types for GEO
### Organization (CRITICAL — every business site)
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 name
- `url`: Official website URL
- `logo`: 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 organization
- `foundingDate`: ISO 8601 date
- `founder`: Person schema
- `address`: PostalAddress schema
- `contactPoint`: ContactPoint with telephone, email, contactType
- `areaServed`: Geographic area
- `numberOfEmployees`: QuantitativeValue
- `industry`: Text or DefinedTerm
- `award`: Array of awards received
- `knowsAbout`: Array of topics the organization is expert in (strong GEO signal)
### LocalBusiness (for businesses with physical locations)
Extends Organization. Critical for local AI search results and Google Gemini.
**Additional required properties:**
- `address`: Full PostalAddress
- `telephone`: Phone number
- `openingHoursSpecification`: Operating hours
**Recommended for GEO:**
- `geo`: GeoCoordinates (latitude, longitude)
- `priceRange`: Price indicator
- `aggregateRating`: AggregateRating schema
- `review`: Array of Review schemas
- `hasMap`: URL to Google Maps
### Article + Author (CRITICAL for publishers)
The 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 title
- `datePublished`: ISO 8601
- `dateModified`: ISO 8601 (critical for freshness signals)
- `author`: Person or Organization schema
- `publisher`: Organization schema with logo
- `image`: Representative image
**Author (Person) required for GEO:**
- `name`: Full name
- `url`: Author page URL on the site
- `sameAs`: LinkedIn, Twitter, personal site, Google Scholar, ORCID
- `jobTitle`: Professional title
- `worksFor`: Organization schema
- `knowsAbout`: Array of expertise areas
- `alumniOf`: Educational institutions
- `award`: Professional awards
### Product (for e-commerce)
**Required:**
- `name`, `description`, `image`
- `offers`: Offer with price, priceCurrency, availability
- `brand`: Brand schema
- `sku` or `gtin`/`mpn`
**Recommended for GEO:**
- `aggregateRating`: AggregateRating
- `review`: Array of individual reviews
- `category`: Product category
- `material`, `weight`, `width`, `height` (where applicable)
### FAQPage
**Status as of 2024**: Google restricts FAQ rich results to government and health sites. 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 schema
### SoftwareApplication (for SaaS)
**Required:**
- `name`, `description`
- `applicationCategory`: e.g., "BusinessApplication"
- `operatingSystem`: Supported platforms
- `offers`: Pricing
**Recommended for GEO:**
- `aggregateRating`: User ratings
- `featureList`: Array of features (strong citation signal)
- `screenshot`: Screenshots
- `softwareVersion`: Current version
- `releaseNotes`: Link to changelog
### WebSite + SearchAction (for sitelinks search box)
```json
{
"@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"
}
}
```
### Person (standalone — for personal brands, authors, thought leaders)
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`
### speakable Property (for voice/AI assistants)
The `speakable` property marks specific sections of content as suitable for voice and AI assistant consumption. Add to Article or WebPage schemas.
```json
{
"@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.
---
## Step 4: Deprecated/Changed Schemas to Flag
| 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.
---
## Step 5: sameAs Strategy (CRITICAL for Entity Recognition)
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.
### Recommended sameAs Links (in priority order)
1. **Wikipedia article** — highest authority entity link
2. **Wikidata item** — machine-readable entity identifier (e.g., `https://www.wikidata.org/wiki/Q12345`)
3. **LinkedIn** — company page or personal profile
4. **YouTube** — channel URL
5. **Twitter/X** — profile URL
6. **Facebook** — page URL
7. **Crunchbase** — company profile (for startups/tech)
8. **GitHub** — organization or personal profile (for tech)
9. **Google Scholar** — author profile (for researchers/academics)
10. **ORCID** — researcher identifier (for academics)
11. **Instagram** — profile URL
12. **Apple App Store / Google Play** — app listings (for software)
13. **BBB** — Better Business Bureau listing (for US businesses)
14. **Industry directories** — relevant vertical directories
### sameAs Audit Process
1. Collect all known web presences for the entity
2. Check that each URL resolves (not 404 or redirected)
3. Verify the Organization/Person schema includes ALL of them
4. Check that the information on each platform is consistent (name, description, founding date, etc.)
5. Flag any platforms where the entity should have a presence but does not
---
## Step 6: JSON-LD Generation
Based on the detected business type, generate ready-to-paste JSON-LD blocks. Always generate:
1. **Organization or Person** (depending on entity type) — always
2. **WebSite with SearchAction** — always for the homepage
3. **Business-type-specific** — Article for publishers, Product for e-commerce, LocalBusiness for local, SoftwareApplication for SaaS
4. **BreadcrumbList** — for any page deeper than homepage
### Generation Rules
- Use the `@graph` pattern to include multiple schemas in one JSON-LD block
- All URLs must be absolute (not relative)
- Include `@id` properties for cross-referencing between schemas
- Use ISO 8601 for all dates
- Include `speakable` on Article schemas with CSS selectors pointing to key content sections
- Place JSON-LD in `<head>` section — NOT injected via JavaScript
### Template: Organization with Full GEO Signals
```json
{
"@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": "support@example.com"
},
"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"
]
}
```
---
## Scoring Rubric (0-100)
| 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 |
---
## Output Format
Generate **GEO-SCHEMA-REPORT.md** with:
```markdown
# 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
```
README.md
What This Does
Turns Claude into a structured data auditor that scores a page for AI discoverability rather than Google rich results. It detects every JSON-LD, Microdata, and RDFa block on a page, validates each against Schema.org, flags what a business of that type should have but doesn't, and generates paste-ready markup for the gaps.
The angle is GEO, not rich snippets. Schema is how AI models identify what an entity IS and how it connects to other entities across the web. The sameAs property gets treated as the highest-value field in the whole spec because it links your on-site entity to Wikipedia, Wikidata, LinkedIn, and Crunchbase, which is the graph AI platforms use to verify and cite a source. Two properties most rich-results guides skip get first-class treatment here: knowsAbout (topics the entity is expert in) and speakable (which passages an AI assistant should read aloud or quote).
This is one skill from Zubair Trabzada's geo-seo-claude toolkit, packaged as a standalone CLAUDE.md.
Quick Start
Step 1: Create a Project Folder
mkdir -p ~/Projects/GeoSchema
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ~/Projects/GeoSchema/
Step 3: Start Working
cd ~/Projects/GeoSchema
claude
Ask "audit the structured data on https://example.com" and Claude works through detection, validation, the sameAs audit, and generation.
The sameAs Entity Graph
The template ranks 14 platforms in priority order, because AI systems weight them differently:
- Wikipedia — highest authority entity link
- Wikidata — machine-readable entity identifier
- LinkedIn, YouTube, Twitter/X, Facebook
- Crunchbase and GitHub for tech companies
- Google Scholar and ORCID for researchers
- App Store listings, BBB, vertical directories
The audit checks each URL resolves, verifies your Organization or Person schema lists all of them, and cross-checks that name, description, and founding date match across platforms. Inconsistent facts across profiles weaken the entity signal.
Schema Types Covered
| Type | When it applies | GEO-specific properties to add |
|---|---|---|
| Organization | Every business site | sameAs, knowsAbout, foundingDate, contactPoint |
| LocalBusiness | Physical locations | geo, openingHoursSpecification, hasMap |
| Article + Person | Publishers | Author sameAs, jobTitle, alumniOf, dateModified |
| Product | E-commerce | aggregateRating, review, gtin/mpn |
| SoftwareApplication | SaaS | featureList, softwareVersion, releaseNotes |
| WebSite + SearchAction | Homepage | potentialAction with a search URL template |
| Person | Personal brands, About pages | knowsAbout, worksFor, award |
| FAQPage | Any page with Q&A | mainEntity array of Question schemas |
Scoring Rubric
Claude scores the site 0-100 across twelve criteria. The heaviest weights:
- Organization/Person schema present and complete — 15 points
- sameAs links, 3 points each up to 5 platforms — 15 points
- Server-rendered rather than JS-injected — 10 points
- Valid JSON and valid Schema.org types — 10 points
- Article schema with full author details — 10 points
Smaller allocations cover WebSite + SearchAction, BreadcrumbList, speakable, knowsAbout, JSON-LD format over Microdata, and absence of deprecated schemas.
Deprecated Schemas It Flags
| Schema | Status | What to do |
|---|---|---|
| HowTo | Rich results deprecated Aug 2023 | Keep for AI parsing, stop promising rich results |
| FAQPage | Restricted to govt/health Aug 2023 | Keep for AI question-answer extraction |
| SpecialAnnouncement | Deprecated 2023 | Remove if still present |
| CourseInfo | Replaced 2024 | Migrate to updated Course properties |
VideoObject contentUrl |
Behavior changed 2024 | Point at the video file, not the page URL |
Generation Rules
When Claude writes new markup it follows a fixed set of constraints:
- Use the
@graphpattern so multiple schemas share one JSON-LD block - Every URL absolute, never relative
@idproperties on each schema for cross-referencing- ISO 8601 for all dates
speakableon Article schemas, with CSS selectors pointing at summary and takeaway sections- JSON-LD placed in
<head>, never injected via JavaScript
Tips
- Fetch raw HTML, not converted markdown. Markdown converters strip
<head>, which is where the JSON-LD lives, so a naive fetch reports zero schema on a site that has plenty.curl -sL <url>works. - Server-render your JSON-LD. Google's December 2025 guidance says JavaScript-injected structured data may face delayed processing, and the rubric docks 5-10 points for it.
knowsAboutwith three or more specific topics is cheap to add and one of the clearer expertise signals available to an AI model.- Migrate off Microdata and RDFa. Both parse worse for AI crawlers than JSON-LD, and the template flags exclusive use of either as a high-priority fix.
Limitations
- The audit reads one page at a time. Site-wide coverage means pointing Claude at each template type: homepage, article, product, location page.
- Valid schema is a claim, not proof. Marking up an award you didn't win still validates. AI platforms cross-check against the sameAs graph, which is why URL consistency matters more than field count.
- Deprecation dates in the reference table are current as of the source skill. Verify against Google's structured data docs before acting on a flag.
- Scores measure markup completeness. They don't predict citation rate on their own, since content quality and brand mentions carry more weight in the full GEO model.