Adding Custom Schema.org Markup on your Page Builder Templates | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will learn:

• An overview of the schema.org configuration screen in Page Builder
• How to change your schema.org Type
• How to configure schema mappings
• How to add new schema types

Overview

Custom Schema allows you to add and adjust the schema.org markup on your Page Builder Templates.

By default, Pages created for built-in entity types will already have schema.org markup based on the entity type to help ensure that your pages are optimized to appear in search. However, because custom entities don’t have a set of predefined fields, you will need to manually configure the schema.org markup on these pages to ensure that your pages are eligible for rich search results.

Overview of the Custom Schema.org Markup Configuration Screen

When configuring the schema.org markup of your Pages, the screen will be broken into three sections: the Code Editor, the Field Reference panel, and the Live Preview.

• Code Editor
  • This is where you can view or configure the mapping used to generate the schema.org markup for the Page.
• Mapping Configuration
  • This is what you will see in the Code Editor. This outlines the data source for each schema.org Property, and this is what you are configuring in the Code Editor to determine the output of your custom schema.
  • The mapping configuration sets the schema.org Properties to add to your pages, and the data sources to use for those Properties. The Pages system uses the mapping configuration to generate the markup on your live pages using information stored in Content.
• Field Reference
  • This shows you a code-like view of all of the data of the entity you are previewing.
  • When you toggle to other entities, you will see the information update based on the content of that Page.
  • If the previewed entity has a field that is empty, that field will not show up in the Field Reference for that Page.
  • You will use the keys in this Field Reference as values in the code editor to determine the mappings.
  • When you use a field name as a value in the mapping configuration, the content from that field will be used as the value in the output of the schema.org markup.
• Live Preview
  • This shows the preview of the Page. You can toggle to view the Page for other entities by clicking on the entity name next to View Content for: and selecting the desired entity from the drop-down.

Schema.org Markup Terminology and Yext Pages

• Type
  • The Type is part of the Schema.org markup hierarchy.
  • In Yext, the Type is based on your Yext Category for that entity in Content.
• Properties
  • Properties are the elements that are associated with the Type you select.
  • For example, if you view the schema.org documentation for the Person Type you will see a list of all of the supported Properties, such as givenName, or hasCredential.
  • Google’s Structured Data Reference provides Google’s recommendations for Properties by Type.
• Values
  • Values are the actual pieces of information stored within these Properties.
  • For example, if the @type is Person, and the Property is givenName, the value would be the specific person’s first and last name.

How to change your schema.org markup

To add custom schema.org markup to a Page Builder Template:

Step 1: Access the Code Editor in the desired Page Builder Template

1. Click Pages in the navigation bar.
2. Click on All Sites.
3. Click Edit next to the desired Site, and click Edit next to the desired Template.
4. Click Settings in the sidebar of the Page Builder Template.
5. Click Customize Schema.org Markup. This will open a Code Editor and a Field Reference section.

Step 2: Change your @type

As we mentioned earlier, the Type is based on your Yext Category for that entity. However, because custom entities do not have categories, you will need to manually update your schema.org Type for Pages built for custom entities.

For a Page Builder Template for a custom entity, the default schema.org markup will look like this:

{
"@context": "https://schema.org",
"@type": "Thing",
"name": "$name"
}

To change your @type:

1. Replace the value for @type based on the appropriate schema.org Type. As a reminder, when determining your Type, we recommend following the instructions in Google’s Structured Data Reference to identify the best Type for your page.
2. This process differs depending on whether you are creating markup for pages for built-in entity types or custom entity types.
   • For custom entity types, you will either need to hardcode the @type, or create a custom field and use a variable to map to that field.
   • For built-in entity types, you don’t necessarily need to do anything to change the @type, as this should be configured correctly by default.
3. To set a specific category for Schema that may be different from the category in Content, navigate to the entity, click on the Categories field, and click Advanced. Then select the Schema category list to override the category.

For example, let’s say we created a Page for a Product entity — we would want to update the custom schema.org markup to reflect this custom Product entity. To do this, we will change the @type from ‘Thing’ to ‘Product’. You can see the information on the Product in Google’s Data Reference .

Step 3: Add the Properties for that @type based on the content of the Page

When adding Properties to the page, it is important that you only include markup for content that is on your Page.

To help you see the properties on the page, you can hide the Live Preview and expand the Code Editor and Field Reference sections, click on the Expand link in the upper-right corner of the Field Reference section.

While keeping to the content on the page, you can also reference the schema.org, and Google Data Reference to determine which fields that we want to map to the schema.org Properties.

For example, in our Product page scenario, we can refer to the Schema.org definition of a product and Google’s Data Reference for a Product to determine which fields we want to map to the schema.org properties.

Step 4: Assign values to those Properties using the Field Reference

The Field Reference will display all of the fields available to map for the given entity.

When adding values, you can either use variables, or hardcode static content. If you hardcode static content, the value of the schema Property will be the same across all Pages. Using variables will make it so that the value of the Schema Property is pulled in dynamically based on the content of this Page.

* Note, variables can’t be used when adding schema.org markup to Finder Pages.

To use variables: Enter a “$” followed by the field name. E.g., "acceptsReservations": "$reservationUrl.url".

• Note: Only the fields in the Field Reference will be available for dynamic mapping.

To hardcode static content: Enter the value for the corresponding Property. E.g., "acceptsReservations": "Yes".

Change your schema mapping

To follow through with our custom product entity example, let’s make sure we add the minimum product schema requirements as dictated by Google. Google requires that we map the image, name, and review, aggregateRating, or offers.

Looking at our custom product entity, the name and image can be dynamically mapped to $name and $logo.image.url, respectively. Let’s also hard-code some content for the offers Property. The result is the below:

{
  "@context": "https://schema.org",
  "@type": "Product",
  "description": "$description",
  "logo": "$logo.image.url",`
  "name": "$name",
  "offers": {`
    "@type": "Offer",
        "availability": "https://schema.org/InStock",
    "price": "0",
    "priceCurrency": "USD"
},
"url": "$websiteUrl.url"
}

Once you have added all of the desired fields and Properties, click Save. Note that, you will not be able to save your markup if there are any syntax errors.

Once you click Save and have validated the changes, you can always test the results of the staging Pages Preview link with Google’s Rich Results Test Tool .

Step 5: Verify that the schema.org markup is correct

Once you save and validate your changes, you will want to verify that your page’s schema.org markup is correct.

To do this:

1. Click on the Share button at the top of the page and copy the Preview Link for the page.
2. Visit Google’s Rich Results Test Tool .
3. Enter the Preview link into the text box and click TEST URL and verify that everything looks correct, and that Google isn’t giving you any errors.

Based on the example of the Product Page, the output result should look like this: