Schema App Highlighter Training

Highlighter – Lesson 1- Select and Name

Training Objective: Select a page, the most appropriate class and a reference name.

How it works

1. Select the page templates you want to mark up.
2. Load a chosen page and select the appropriate schema class.
3. Map each of the elements on the page to the schema markup properties.
4. Define the pattern for each template.
5. Review and deploy.

What you’ll love

• Optimize template pages with no coding.
• Create “connected” markup at scale.
• Contains the entire schema.org vocabulary + extensions (e.g. health, automotive, finance, etc.).
• Can be visible to all search engines and assistants.
• You can control where your markup resides.

Watch an overview of the Highlighter here:

1. Open the Schema App Highlighter and click New Template

2. Paste in the URL for the first page & choose a class

Highlighter – Lesson 2- Tag First Page

Training Objective: Tag your chosen templated page with schema markup.

Several Options Available

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 “Sub-template”
3. Link an existing data item
4. Apply a fixed property

Watch how to create product markup with the Schema App Highlighter:

Option 1: Tag content on a page

Hover your cursor over the content on the page. An orange box will surround the content that is eligible for markup.

1. Click to select the content. Clicking will open a highlight on the right side of the page.
2. Select the property that best describes the highlighted content. In the example below, we’ve selected “Headline” property.

See it in action: Watch this Video (Add “Headline” highlight to content)

Sometimes schema.org requires further clarification. A schema.org type (aka class/entity/data type) may have properties that can be further broken down into a new schema.org type (with its own set of properties). When this is the case, both the Schema App Editor and Highlighter will present you with available options specific to that property so you can select the one that best aligns to your content.

For example, highlighting a picture for an “Video” property will direct you to an additional type/class called “VideoObject”, which contains a property, “Video”. The Highlighter will narrow down the available 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.

Example: Watch this Video (Select an additional class for your property)

Click to “Reveal Content” on a page

If you want to expose all of the content on a page, that might be hidden in an accordion, slider, etc., click “Reveal Content” from the drop down menu in the top left corner of the Highlighter.

Option 2: Add a Sub-Template

There are two situations for which this option makes sense:

1. There is a section within your page that contains content that repeats – for example, a collection of things such as a list of job postings that display the title, a short description and the author. In this case, you could mark up the first job posting and apply the same markup to all of the other job postings. 
2. When you have one section on a page (with a different class type than the page itself) that shares the same sub-class.  For example, the primary page is an “Article” which contains the name of the author and their picture. On the same page, there is reference to the name of an author and the title of the article. If you don’t differentiate the two sections, you’ll confuse the search engine.

Helpful tip! Click and drag your cursor around the item (to add a bounding box around the thing that you want to highlight). Be sure to capture all of the properties associated with it. Start small and expand your box so that you only capture the items that are relevant to your thing, adding nothing additional.

Add a sub-template step-by-step

1. Click the “Add a Template” button

2. Click on part of one of the entities that you wish to create a template for. In this case, we are marking up a blog in our “Recent Post” section.

3. Once you’ve selected the entity the “Highlight Content” box appears on the right-hand side of the page. Now you can increase the scope (or widen) your selection to capture all of the information you wish to mark up.

4. Choose one of the articles to Highlight.  In this example, we leveraged the “mentions” Property option and “BlogPosting” Class to weed out anything else that might appear on our Recent Posts listing.

5. Leverage Property = “mentions” to select only Blogs from the list of recent posts

6. Click save!

Option 3: Link Existing Data Items

Using the “Link Existing Data Items” functionality we can link to a Data Item that we previously marked up (potentially in the Schema App Editor). 

When you link, via schema.org, 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.

1. Click the “Link Existing Data Item” button.

2. Select the property that is to be defined.  We have chosen “Publisher”.

Image: Choose the property, leave class empty

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.

Search for the data item by name. In our case, since the data item for the company Schema App was created during the Organization markup, it appears in the search box.

3. Click on the name of the data item and save!

Option 4: 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:

Click on the “Add Fixed Property” button

This will launch a highlight that will capture static content. By nature, all manual highlights will be the same across all pages.Enter the relevant TEXT in the “Value” field that applies.  For example, we used the Value of “en-US” and the property inLanguage:

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.

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

Highlighter – Lesson 3 – Create Page Set

Training Objective: Tell the Schema App Highlighter how to find all of the pages that will require the same markup.

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:

• 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. This option might make sense if the URLs don’t change over time but if you are constantly adding products, services, blogs, etc., to your website, it isn’t the best choice.

Option 2: Define Pattern

This option allows you to define a URL segment pattern to define the page set.

For example: /news/**

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

Process:

1. Define URL segment pattern
2. Click “Add URL Examples”
3. Add URL examples
4. Click “Validate URLs”
5. Check that the URLs are Valid

A red “x” indicates that pages are not valid. If a URL does not validate it means that it does not match the indicated URL pattern. You’ll have to correct this before moving on, whereas a checkmark indicates that pages are valid

        6. Click “Next”

Option 3: Use Defined XPath

1. Decide which element in the page to use

Choose an element on the page that is common to all pages that share the same template. For example, if you were marking up blogs, you might use the blog author’s name or if you were marking up products, you might use the Item # – anything that is unique and consistent to all similar items.

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

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

4. Paste the XPath underneath where it says “Xpath”

5. Test with at least 3 URLs by clicking “Review URLs”

When using a defined X-path, it’s a good idea to review a couple pages that you do not expect to find that x-path on. That way you can confirm that the template is also invalid on pages where the x-path would not be present.

6. If all looks good, then click NEXT

If you want to learn more about writing or narrowing down xpaths this is a good resource when starting out: https://www.softwaretestinghelp.com/xml-path-language-xpath-tutorial/

Highlighter – Lesson 4 – Review Highlights

Training Objective: Validate that each property is being successfully mapped to the correct content on the page. Publish the template.

The Highlighter validates using the example URLs, URL patterns, or x-paths previously captured.

 Check that:

1. The “Highlight content” is referring to the page you are validating
2. There is a highlight for each property from our 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 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.

Review remaining pages

Depending on how many sample pages you provided when creating the page set, you will see “Page X of X” at the top left hand corner. Page 1 is the original page you loaded when you began highlighting, and all the sample pages are compared to it. 

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

Continue reviewing until you reach the final page.

Once ready click “Next”

Final validation

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.

Go through and check that for each page URL set, the properties are listed with the correct information!

Save & Finish

Once you’ve confirmed all is well and good, click Save & Finish!