Help Center
< All Topics

How To Fix mainEntity Schema Issue In Schema Package

The mainEntity property is an important part of structured data. It helps search engines clearly understand what the primary subject of a page is. If mainEntity is missing, incorrect, or duplicated, Google’s Rich Results Test or Schema Validator may show warnings or errors.

This guide explains what the mainEntity issue is, why it happens, and how to fix it using the Schema Package plugin.

What Is mainEntity in Schema Markup?

mainEntity is used to define the primary entity being described on the page.

Examples:

  • On a Blog Post page → the main entity is the Article
  • On an FAQ page → the main entity is the FAQPage with its questions
  • On a HowTo page → the main entity is the HowTo

Search engines use mainEntity to:

  • Understand page intent
  • Connect related schema types
  • Display rich results correctly

Common mainEntity Issues

You may see issues like:

  • ❌ Missing mainEntity
  • ❌ Multiple schemas competing as mainEntity
  • ❌ Wrong schema type set as mainEntity
  • ❌ Nested schema incorrectly placed inside mainEntity

These issues usually appear when:

  • Multiple schema types are added to the same page
  • Global and post-specific schemas overlap
  • Manual JSON-LD is added incorrectly

How Schema Package Handles mainEntity

Schema Package automatically manages mainEntity when configured correctly.

The plugin decides the mainEntity based on:

  • Schema placement (Global / Post Type / Post Specific)
  • Schema type priority (Article, FAQPage, HowTo, etc.)
  • Whether the schema is set as the primary schema for the page

Step-by-Step: Fixing mainEntity Issue

Step 1: Identify the Page Showing the Error

  1. Copy the affected page URL
  2. Test it using:
    • Google Rich Results Test
    • Schema Validator
  3. Note which schema type is showing the mainEntity warning

📸 Screenshot Placeholder: Rich Results Test showing mainEntity warning

Step 2: Check All Active Schema Types on the Page

Go to:

WordPress Dashboard → Schema Package → Dashboard

  • Identify schemas applied via:
    • Global rules
    • Post type rules
    • Specific post rules

Make sure you know how many schema types are active on the same page.

📸 Screenshot Placeholder: Schema Package dashboard with active schemas

Step 3: Set Only One Primary Schema

Each page should have only one main schema acting as the mainEntity.

Examples:

  • Blog post → Article
  • FAQ page → FAQPage
  • How-to guide → HowTo

If multiple schemas are active:

  • Keep one schema as the primary
  • Others should act as supporting schemas

📸 Screenshot Placeholder: Schema selection screen highlighting primary schema

Step 4: Fix mainEntity Using Schema Package Generator (Post-Specific)

If the issue is on a specific post:

  1. Open the post editor
  2. Scroll to Schema Package Generator
  3. Review all added schema types
  4. Remove unnecessary schema types
  5. Keep the most relevant schema for the content

Tip: Long or complex content may still use multiple schemas, but only one should be the main entity.

📸 Screenshot Placeholder: Schema Package Generator inside post editor

Step 5: Avoid Duplicate Article Schemas

A common issue occurs when:

  • WordPress theme adds an Article schema
  • Schema Package also adds an Article schema

Solution:

  • Disable schema output from the theme (if possible)
  • Or disable the Article schema from Schema Package for that page

📸 Screenshot Placeholder: Theme schema settings disabled

Step 6: Validate After Fixing

After making changes:

  1. Clear cache (plugin/CDN/server)
  2. Re-test the page URL
  3. Confirm:
    • No mainEntity warnings
    • Correct schema type is detected

📸 Screenshot Placeholder: Successful schema validation result

Best Practices to Avoid mainEntity Issues

  • ✅ Use one primary schema per page
  • ✅ Add extra schemas only when they truly apply
  • ✅ Prefer Schema Package Generator for post-specific control
  • ✅ Avoid mixing manual JSON-LD with plugin-generated schema
  • ✅ Regularly test pages after schema changes

Frequently Asked Questions

Can I use multiple schema types on one page?

Yes. Schema Package fully supports multiple schema types, but only one should be the mainEntity.

Does Google require mainEntity?

It is not always mandatory, but strongly recommended for clarity and rich results eligibility.

Will Schema Package automatically fix this?

Schema Package handles most cases automatically, but manual review is recommended for complex pages.

Final Notes

Fixing the mainEntity issue ensures:

  • Better schema clarity
  • Improved search engine understanding
  • Higher chances of rich results

If you still face issues, review your active schemas carefully or contact Schema Package support.

Need help?
Visit: Schema Package → Support

Table of Contents