Product schema missing a nested AggregateRating

What Is This Issue

Product or LocalBusiness schema is present, but the nested AggregateRating schema is missing or incomplete. AggregateRating provides summary review information (average rating, review count) that enables star ratings to appear in search results.

Without AggregateRating schema:

Star ratings won’t appear in search results
Users won’t see social proof before clicking
Rich snippets showing review counts won’t display
Competitors with ratings may get more clicks

A proper AggregateRating schema should be nested inside Product, LocalBusiness, Recipe, Movie, or other reviewable schemas and include: ratingValue, reviewCount, bestRating (default 5), worstRating (default 1), and optionally ratingExplanation.

Why Is This Important

AggregateRating schema significantly impacts click-through rates and trust:

Star ratings in search: Pages with star ratings get 35% more clicks on average
Social proof: Users trust businesses and products with visible ratings
Rich snippets: Enables review count and rating display in search results
Local SEO: LocalBusiness with ratings appear more prominently in maps
AI search signals: AI engines use rating data to recommend top-rated options

Resolving this issue improves your SEO health score by adding powerful social proof signals that increase click-through rates and user trust.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing or incomplete AggregateRating schema:

Find reviewable schemas: The crawler identifies pages with schemas that commonly have ratings:
- Product
- LocalBusiness (and subtypes)
- Recipe
- Movie, Book, Course
- Any schema with review or aggregateRating properties
Check for AggregateRating: The crawler examines whether the schema has an aggregateRating property
Validate AggregateRating structure: If present, the crawler checks:
- Does it have @type set to AggregateRating?
- Does it have ratingValue?
- Does it have reviewCount?
Validate rating values: The crawler verifies:
- ratingValue is a valid number
- reviewCount is a valid integer
- ratingValue is between worstRating and bestRating (if specified)
Check page consistency: The crawler compares the schema rating with:
- Visible ratings displayed on the page
- Any review properties also present in the schema
Trigger conditions: The issue is flagged when:
- A reviewable schema exists BUT aggregateRating is missing
- aggregateRating exists but ratingValue is missing
- aggregateRating exists but reviewCount is missing
- ratingValue is outside the valid range

How To Fix

Identify reviewable content: Check pages with Product, LocalBusiness, Recipe, Movie, Book, or similar schemas

Add AggregateRating to your schema:


{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product Name",
  "description": "Product description",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "125",
    "bestRating": "5",
    "worstRating": "1"
  },
  "offers": {
    "@type": "Offer",
    "price": "29.99",
    "priceCurrency": "USD"
  }
}

Use correct values:
- ratingValue: Numeric value as string (e.g., “4.5”)
- reviewCount: Integer as string (e.g., “125”)
- bestRating: Usually “5” (default if not specified)
- worstRating: Usually “1” (default if not specified)
Ensure ratings are legitimate:
- Only use real reviews from actual customers
- Don’t create fake reviews or manipulate ratings
- Make sure the rating matches what’s displayed on the page
Validate with Google’s Rich Results Test

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
Structured Data Validation — The extracted schema is validated against Schema.org definitions
Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

Examples

Example 1: Missing AggregateRating in Product Schema

Problematic state (Product without AggregateRating):


{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "description": "High-quality wireless headphones"
}

Missing aggregateRating property

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Wireless Headphones",
  "description": "High-quality wireless headphones",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "125",
    "bestRating": "5",
    "worstRating": "1"
  }
}

Example 2: AggregateRating in LocalBusiness Schema

Corrected state (LocalBusiness with ratings):


{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Coffee Shop Downtown",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "342",
    "bestRating": "5",
    "worstRating": "1"
  }
}

Example 3: Incomplete AggregateRating Schema

Problematic state (missing required properties):


{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Chocolate Chip Cookies",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "5"
  }
}

Missing reviewCount property

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "Recipe",
  "name": "Chocolate Chip Cookies",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "5",
    "reviewCount": "89",
    "bestRating": "5",
    "worstRating": "1"
  }
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-156-aggregaterating-schema.test.js

Purpose

Validates that the crawler correctly validates Product schemas with nested AggregateRating schemas and does not report false positives when the nested AggregateRating has required properties.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 156
Issue Code: aggregaterating_schema_nested
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

Valid nested AggregateRating: Product schema has an aggregateRating property with a nested AggregateRating containing ratingValue and reviewCount — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a Product schema has a valid nested AggregateRating with ratingValue and reviewCount.

Fail

No negative test cases are defined.

Validation

Correct pass-through of valid nested AggregateRating schemas
Graceful handling of empty HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers valid nested AggregateRating schema detection
Covers empty HTML resilience

References

Google: Product Structured Data (Ratings) — Google Search Central
Schema.org: AggregateRating — Schema.org
Google: Review Snippet Guidelines — Google Search Central