Strategy: Determining the Primary Entity of a Page

A page's Primary Entity is defined using the type which best describes the central content of the page. The type you select will have implications with respect to how you can connect the page to other entities (internal and external). Having valid, accurate typing and relationships will impact the quality of your knowledge graph & its ability to be used for inferencing.

This document outlines some common scenarios when determining the primary entity of a page and potential strategies to target all the relevant content.

TABLE OF CONTENTS

• Scenario 1: Page is about a single entity, and I can access all the properties I need
• Scenario 2: Page is about a single entity, but not all properties I need are accessible
  • Option 2.1: The Primary Entity reflects the primary content described & is the "subjectOf" a WebPage
  • Option 2.2: The Primary Entity is a WebPage, which has a "mainEntity" that reflects the primary content
• Scenario 3: Page is about several, equally important and distinct entities
  • Option 3.1: The Primary Entity is a Collection Page
  • Option 3.2: The Primary Entitiy is an ItemList or OfferCatalog
  • Option 3.3: The Primary Entity is an WebPage with connections to the primary content
• Scenario 4: It is unclear what the page is about
  • Option 4.1: The page is confusing or unclear
  • Option 4.2: The page is a stub or has an insufficient amount of content

Scenario 1: Page is about a single entity, and I can access all the properties I need

The easiest scenario! In this case, the page is clearly about a single thing (e.g a Product, a Service, a Person). Use the type that best describes the primary entity and connect all attributes to the primary type.

However, there may be content on the page that you wish to include in your markup, but the Type of your primary entity doesn't give you access to the necessary properties. In this case, proceed to Scenario 2.

Scenario 2: Page is about a single entity, but not all properties I need are accessible

A common example of this scenario might be when a page is about a Product or Service and includes additional content which provides context, but isn't necessarily a description of that Product/Service. Another scenario might involve entity linking, again where the entities provide context but aren't necessarily directly related to the primary entity.

In these cases, we have options! The option you should use is determined by both the content and the intent of the page.

Option 2.1: The Primary Entity reflects the primary content described & is the "subjectOf" a WebPage

Use this to say that the parent entity is one of the primary topics of the WebPage. This is the equivalent to saying that the WebPage is "about" the primary content. From here you may use WebPage properties like "about" or "mentions" to reference the other content on the page.

Note: Include the URL of the WebPage to reiterate that the PrimaryEntity and the WebPage have the same "entity home". 

Option 2.2: The Primary Entity is a WebPage, which has a "mainEntity" that reflects the primary content

Use this to say that the primary content is the main focus of that particular WebPage. From here you may use other WebPage properties like "about" or "mentions" to reference the other content on the page.

Scenario 3: Page is about several, equally important and distinct entities

There are several great options to describing a page that contains a variety of content about more than one entity.

Option 3.1: The Primary Entity is a Collection Page

A Collection Page is a useful type for referencing a WebPage with several content components or areas of focus. Use the "hasPart" property to reference each of the content components (e.g Videos, FAQs, ItemLists, etc). Use the the "about" and "mentions" properties to reference the subject matter of the Collection Page as a whole, or the individual content components. 

Option 3.2: The Primary Entity is an ItemList or OfferCatalog

An ItemList, or the more specific OfferCatalog, is a useful type when a WebPage lists multiple equally important entities. An example could be a page that lists all of the schools belonging to a particular School District. Alternatively, it could be a page that describes all the Products offered by an Organization that fit a certain criteria.  

Option 3.3: The Primary Entity is an WebPage with connections to the primary content

If Options 3.1 and 3.2 don't apply, Option 3.3 likely will. Use the "mainEntity", "about", and "mentions" to indicate the subject matter or content of the page. Use "hasPart" to indicate individual content components (e.g Videos, Articles, FAQs, etc).

Scenario 4: It is unclear what the page is about

This happens more often than you might think! Common examples of this scenario include:

• The page being a stub or having relatively little content
• The page content is confusing or incorrect
• The page has lots of content, but it's unclear what's important.

Option 4.1: The page is confusing or unclear

Contact the subject matter experts or content teams responsible for the page to ask for clarity regarding the intent and content of the page. This conversation may lead to a better understanding of how to structure your schema markup. The conversation may also reveal important information gaps in the content that need to be addressed by the content team

Option 4.2: The page is a stub or has an insufficient amount of content

Collaborate with the content team to determine whether the page or topic is important enough to warrant revision.