Purpose: This is a high-level overview of the Schema App Highlighter. For more details, consider accessing our Highlighter Training Lessons.

Plan

Select the templated page type that you want to mark up

A page template utilizes the same layout for a specific type of content (e.g. products, services, blogs, job postings, FAQs).

Choose a web page to highlight.  An ideal page will be one that represents many (possibly hundreds or thousands) of similar pages. Throughout this training, we will work through an example of a Product from Keen.

Next, you’ll want to plan your strategy. A good first step is to see if the item you’re marking up is eligible for rich results according to Google’s Documentation. If it is, look at what the required and recommend properties are for the type of template you’re creating. In this case, Products are eligible for rich results provided the markup contains the required properties.

If you’re creating a template for something that isn’t eligible for rich results, like a Service, we recommend looking at the available properties listed in the Schema.org entry, and creating a table to guide your process. It should capture the following headings:

Primary URL  / Class  /  Properties   /   Similar URLs (3) / Pre-requisite / Tagging Method

Decide which Schema Class to use

Use the Schema.org class type that is the most specific while still being accurate. In our case we are creating markup for a product, so we will use the schema class, Product. A quick way to search for the best schema class is to use the class tree in the Schema App Editor (aka Structured Data Editor). Simply start with the most generic class, which is a “Thing”, and drill down until you reach the most specific and accurate class description. Alternatively, you can type in a class name if you have a pretty good idea what it might be called.

Decide & document which Schema Properties to use

Properties are used to further describe the thing that we are creating markup for. The best way to determine which properties to use is to create a data item in the Schema App Editor tool and look through the properties listed in the Form Builder. The tool categorizes the properties into, “Required”, “Recommended” and “Other” Properties. You DO NOT have to use EVERY property, however, you should use all of the “Required” properties. This is because the required properties are necessary for Rich Result eligibility. The recommended approach is to think about what you believe is important to call out about the thing you’re creating the markup for and use the available properties to do so.

Create a list of these properties.

Determine the order to markup the content

If you want to link content from one page to content on another page, be sure to create the data item in the order that makes sense. For example, you may want to link a templated “services” page to your homepage, in which case, you would first mark up your homepage (using the Schema App Editor) before starting to build the “services” page in the Schema App Highlighter.

Load Page

Open Schema Highlighter and Click New Template

1. Insert the URL of the page you’re using to create your template.
2. Select the appropriate class, in this case it’s Product.
3. Click “Load Page”

 

Tag First Page

There is a good chance that you won’t be able to use the same method to tag all of the content on your page, so depending on the type of content and its structure, the Highlighter contains different options.  We recommend that you consider each option in the following order:

1. Tag content on a page
2. Add a fixed property
3. Link to an existing data item
4. Add a “Sub-template”
5. Add a manual xpath

After you’ve identified how you’ll tag the content, go back to your spreadsheet to identify the “Tagging Method”.

Option 1: Tag content on a page

 

1. Hover your cursor over the content on the page. An orange box will surround the content that is eligible for markup.
2. Click to select the content. Clicking will open a highlight on the right side of the page.
3. Select the property that best describes the highlighted content. In the example below, we’ve selected the “name” property.

4. Sometimes schema.org requires further clarification. In these cases, you may be required to select an additional class for your property.  For example, highlighting a picture for the “Image” property will require a class of “ImageObject” and sub-property of “url”. The Highlighter will narrow down the options for you. If you aren’t sure what to choose, we recommend that you go to Schema.org to read the short definitions of the options.

 

 

Option 2: Add Fixed Property

You can use the “Add Fixed Property” option when you need to further define something that:

• Resides in the same place on every page
• Is consistent
• Needs further definition

Examples:

• A currency symbol that always represents USD
• Inventory that is always “in stock”
• Inventory that is always in “new condition”
• Blogs that are always written in “English”

Process:

1. Click on the “Add Fixed Property” button
2. Insert the Value, for example USD (the ISO currency code for U.S. dollars)
3. Connect it to the appropriate property and class (refer to schema.org for clarification)

Click “Save”!

 

Option 3: Link Existing Data Items

When you link the content on a page to another page, you improve the crawlability of your website while building a knowledge graph. In this example, the reader may want to learn more about an author who has written an article. Using the “Link Existing Data Items” functionality we can mark up the link that brings the reader to another part of the website that provides details about the author.

Process:

Prerequisite: Markup the page you will be linking to first.

1. Click the “Link Existing Data Item” button.
2. Select the property that is to be defined.  We have chosen, “brand”. You may be requested to fill in the Class. Leave this as, “No Class Selected” because the schema class will already be defined within the data item we are linking to.
3. Search for the data item by name.

Click “Save”!

Option 4: Add a Subtemplate

There are two situations for which this option makes sense:

1. 1. There is a section within your page that contains content that repeats. e.g. a list of reviews for your product that an author, a review body, and a rating. In this case, you could mark up the first review and apply the same markup to all of the other reviews provided they follow the same format.
   2. There may be more than one section on a page (with a different class type then the page itself) that shares the same sub-class.  If you don’t differentiate the two sections, you’ll confuse the search engine.

Example: Subtemplate

Click the “Add Template” button

Click on one of the entities that you wish to create a template for. In this case, we are marking up one of a list of reviews for our product. Once you’ve selected the entity the “Template Highlight” box appears on the right-hand side of the page.

You can increase the scope (or widen) your selection to capture all of the information you wish to mark up.

Choose the Property and Class – in this example the review property connects the Product template to a Review data item subtemplate. Since this is a subtemplate, leave the Template Highlight as a Class. Other items will be linked within this subtemplate using properties.

From within this subtemplate, you can further click to highlight items, or use one of the other methods to select your subtemplate items.

Click save!

Option 5: Add a manual xpath

Sometimes dynamic information will appear on the live page that isn’t rendered in the Highlighter. In cases like these, you may want to use a manual xpath. To do this, go to the live page, right-click on the element you want to highlight, and click “Inspect”.

Ensure you’ve found the correct element within the HTML, and then right-click, choose “Copy”, then “Copy XPath”.

Process:

Prerequisite: Copy the Xpath for your selected element

1. Click the “Add Manual Xpath” button.
2. Paste the Xpath you copied into the Xpath field.
3. Select the appropriate properties and classes if required.

Click “Save”!

Validate for Completeness

Scroll through the saved highlights on the right side of the page. Ensure that you have a highlight for each property in your list. You can also click “JSON-LD” to preview your markup and test it with Google.

Delete a highlight (if necessary) by clicking the “x” on the top right-hand side of a specific highlight.

Click Next

Create Page Set

Now that you’ve highlighted your content, you want to tell the Schema App Highlighter which pages you want to apply the highlights to.

There are 3 options to choose from:

• List URLs
• Define Pattern
• Define XPath

Each option is a different method of defining the Page Set for your Template

Option 1: List URLs

This option allows you to use a list of specific URLs to define the page set.

Simply enter all the URLs you wish to apply the template to, and click “Review URLs”

Click “Edit” to add or delete URLs from your list. If your URLs are correct, click “Next”.

Option 2: Define Pattern

This option allows you to define a URL segment pattern to define the page set. For example, if all product pages contain /p/ with a variable at the end, you would enter the URL pattern: /p/**

The first “/” tells the Schema App Highlighter to ignore everything that comes before the “/”. The asterisks tell the Highlighter to apply the rules to any variable that follows “/p/”.

Process:

1. Enter URL segment pattern in “Pattern to match:” field.
2. Add at least 3 URL examples from the table you prepared
3. Click “Validate” to ensure the URL pattern matches the URLs you provided

A check mark indicates that pages are valid, and a red “x” indicates that pages are not valid:

Click “Edit” to add or delete URLs from your list. If your URLs are valid, click “Next”.

Option 3: Use Defined XPath

Choose an element on the page that is common to all pages that share the same template. Using the product page as an example, I’m selecting the aggregate rating. The product template we created will only deploy to the pages containing that xpath.

Once you know which element you’d like to use, you can right-click on it in the live page and choose “Inspect”.

Ensure you’ve found the correct element and then right-click, choose “Copy”, then “Copy XPath”.

Process:

1. Paste the xpath into the “XPath” field.
2. Add at least 3 URL examples from the table you prepared
3. Click “Review URLs” to ensure the xpath exists on the example pages you provided

Ensure that none of your URLs are excluded from the xpath pattern. In the example provided, an OfferCatalog page has also been included in the list of URLs. Seeing that it isn’t being excluded shows that the chosen xpath is too broad and so is deploying to other pages outside of the product detail pages the template was created for. If this happens, select an xpath for a different element that is unique to the product detail pages.

Click “Edit” to add or delete URLs from your list. Once you’ve ensured everything is valid, click “Next”.

Review Highlights

Validate that each property is being successfully mapped to the correct content on the page. The Highlighter validates using the example URLs previously captured. It will show you both the “Original Highlight” from the page used to create the template, and the “Highlight content” for each example URL you used to define your page set.

 

Check that:

1. The “Highlight content” is referring to the page you are validating
2. There is a highlight for each property from your list.
3. The “Highlight Content” is correct

Troubleshooting

“No matching X-path” errors

Not every page set will be perfectly templated. Sometimes, the content on the page that we’ve highlighted to define a property won’t be in the exact same place page-to-page. When this happens you’ll get an error message: “No matching xpath”.

DO NOT DELETE THE HIGHLIGHT. Instead, create a new highlight for the missing content. Moving forward the Schema App Highlighter will look at both spots for content to define a property. By creating another highlight, we’re building a cascading template that will be able to recognize when the information you want highlighted is contained in different places!

Revalidate the highlights for accuracy.

Proceed to Page 3

Reviewing the page should be much faster, as there should be fewer highlights (if any) with a missing xpath.

Perform the same review on page 4

This is the last page to be reviewed!

Once ready click next

Review & Publish

Given that you may be marking up 1,000s of pages, it is important to do one final review of the highlights before you publish. This can be done in the Summary section which provides an overview for each page set URL, and its associated properties. If there are any errors or issues, such as the ones shown in the image below, go back and review your highlights and page set configuration.

Once you’ve confirmed all is well and good, click “Save & Finish”.

Deployment Method

There are 3 deployment options:

• Embedded Javascript Parser
• Crawl + Integration
• JavaScript + WebHooks

Convert the publish “Status”from “Draft” to “Published”.

Test your pages using the Structured Data Testing Tool or the Schema Markup Validator!

For more details about creating schema markup for products, consider accessing our tutorial Creating “Product” Schema Markup Using the Schema App Highlighter.