Schema markup and structured data ultimate guide (JSON-LD)

Updated: Jul 28

Do you want to learn how you can create and add Schema markups to your website by using JSON-LD?


If so, keep reading this ultimate guide.


In this article, not only will you find information about rich snippets and Schema structured data, but you will also learn how to write JSON-LD and generate all the markups you want.


I’ll tell you exactly how to use schema.org to create your very own structured data markups.



Table of contents

  1. What Schema markups are;

  2. What rich snippets are;

  3. Free Schema markup generators;

  4. How to use schema.org;

  5. 7-step structured data workflow;

  6. Understanding the syntax of JSON-LD;

  7. How to create structured data with JSON-LD (workshop).






SCHEMA MARKUPS




In 2011, Google, Microsoft (Bing), Yahoo! and Yandex launched schema.org, an initiative to provide a commonly shared vocabulary for structured data.


Structured data is used by webmasters to help search engines understand published content on a web page.


Schema’s mission statement (source: schema.org, info retrieved on May 2020):


Schema.org is a collaborative, community activity with a mission to create, maintain, and promote schemas for structured data on the Internet, on web pages, in email messages and beyond.


What are Schema markups?

Schema markups are snippets of code webmasters usually insert in the header of web pages to further describe and specify online content for search engines.


Search engines use this data to interpret online content and display more appropriate information in the SERP (Search Engine Results Page)


When you use HTML tags on your web pages, you are telling browsers how to display information, including the tag (if you want to know what an HTML tag is, read my following bonus paragraph).


Web users experience depends on the relationship between data representation and presentation. HTML tags are data representation.

For example:


<h1>Schema markup SEO guide</h1>

tells browsers to display the text string “Schema markup SEO guide” in a heading 1 format. Nevertheless, the HTML tag doesn’t give any additional information on what the text string means.


“Schema markup SEO guide” can be a title of a blog post or the title of a book that you can actually purchase.


It’s difficult for search engines to correctly understand the context of a text string and display to a user the right search results accordingly.


So, schema.org provides context to help search engines interpreting online content.


Be aware that search engines compare Schema markups information with the page content. If they don’t match, search engines will not consider your structured data and could also penalize you.


In other words, if you insert a Review markup (I’ve explained what it is later), but in your page you don’t actually have any reviews, Google doesn’t consider this markup valid.


To write Schema markups, webmasters can use Microdata, RDFa or JSON-LD formats.


In this article, I’ll only focus on JSON-LD format, since Google recommends it.


Google recommends using JSON-LD for structured data markups whenever possible. Screenshot from the page “Understand how structured data works” published by Google Developers.


Why is Schema structured data important for SEO?

In a 2018 Reddit AMA (Ask Me Anything), John Mueller, senior webmaster trends analyst at Google, stated that Schema markups help rankings.


We do use [structured data] to understand a page better, it helps us to rank it better where it’s relevant.

John Mueller, webmaster trends analyst at Google, explains why Schema markups affect rankings. Screenshot from TechSEO AMA (Ask Me Anything) on Reddit, 2016.

Adding Schema structured data in your website’s HTML is one of the many SEO (Search Engine Optimization) activities you should include to ensure optimal performance in the search.


If structured data helps Google understand a page better, it may rank higher in the SERP or rank for additional keywords.


Nevertheless, on the 2nd of April 2018, Mueller Tweeted that Schema markups are not a ranking signal. It means your website doesn’t rank higher just because you’ve added Schema structured data on your pages.


In 2018, John Mueller, webmaster trends analyst at Google, posted a Tweet stating that Schema markups are not ranking signals.

In other words, RankBrain (Google’s machine-learning AI algorithm) doesn’t directly consider structured data as a ranking signal to determine the most relevant results to search engine queries.



Bonus: what is an HTML tag?

Just to have a complete overview on Schema markups, I’ve decided to write this brief paragraph on what an HTML tag is.


A tag is a command inserted in the code of a web page which tells browsers to do something (e.g. perform an action, display content accordingly and so on).

Tags are enclosed in between a single left and right angle quote: “<” and ”>”.


HTML is a language that you can use to express these tags: <html>.


Example of HTML tag:


<!DOCTYPE html>
<html lang="en">
<head>
  <title>Title of the document</title>
</head>
<body>
<h1>This is a heading</h1>
<p>This is a paragraph.</p>
</body>
</html>

This is what it means line by line:

  1. Doctype declaration of the document. In this case HTML5;

  2. It indicates the start of an HTML document in English (language of the document);

  3. It’s the first part of the HTML document that search engines and browsers read. It’s not visible on the web page;

  4. It represent the title of the document (or web page) and it is displayed from search engines in the SERP and from browsers in the window tab;

  5. End of the head section (or header);

  6. Begin of the body section: this content is visible on the page;

  7. It represents a heading 1: it tells search engines what the web page is all about and commands browsers to display the text string in between the tags with a heading 1 format;

  8. It represents a paragraph: it provides search engine information about the page and commands browsers to display the text string in between the tags with a paragraph format;

  9. End of the body section;

  10. End of the document.





RICH SNIPPETS




When search engines process Schema markups, they may display additional information in the SERP to help users in their search. This additional information is called rich snippets or rich results.



What are rich snippets?

Rich snippets (or rich results) are search results with additional information displayed. Rich snippets are the results of Schema markups and their data is pulled from the structured data found in a page’s HTML.


This is a Google search result without rich snippets:


Example of Google SERP without rich results.

This is a Google search result with a rich snippet:


Example of search result with a rich snippet. In this case, the rich snippet is represented by a list of FAQs, because the landing page has the FAQPage Schema markup installed.

Many entrepreneurs ask me how they can add rich snippets to their website.


This question is completely wrong.


Just to clarify, rich snippets are a result of structured data. You add Schema structured data in your website’s HTML to generate rich results.


So, the right question should be how to add Schema markups in a website to generate rich snippets.


I’ll show you how in a moment.



Why are rich snippets important for SEO?

Rich snippets mean higher organic CTR (Click-Through-Rate).


It’s not a secret that a rich result stands out more from the others and an eye-catching search result translates into more clicks.


The percentage of users that click on a search result determines the CTR.


When the CTR doesn’t refer to paid search results (e.g. Google Ads), it is called organic. In SEO jargon, organic means “free”, a result that you attained without paying money.


CTR is a key ranking signal.


In 2016, Larry Kim’s study demonstrated the correlation between CTR and search rankings (see image below).


CTR vs. organic search position. Larry Kim used 1,000 keywords in the same keyword niche (to isolate external factors like Google shopping and other SERP features that can alter CTR characteristics). The keywords are all from his own website: WordStream.com. He compared CTR versus rank for 1-2 word search terms and did the same thing for long-tail keywords (4-10 word search terms).

Every time your pages beat the expected organic CTR for a given position, you gain an opportunity to to appear in higher organic positions.


Also Google has confirmed multiple times the extreme importance of organic CTR for rankings.


During SMX (Search Marketing Expo) West 2016, Paul Haahr, software engineer at Google, presented how Google algorithm works from an engineering perspective.


Slide 30 of Paul Haahr, software engineer at Google, presented during SMX (Search Marketing Expo) West 2016.

In the slide above, Haahr shows that it is “bad” if users don’t click on a search result. He explains that Google runs A/B tests on real traffic and to check changes in click patterns:


We run a lot of experiments. It is very rare if you do a search on Google and you're not in at least one experiment.

In March 2015, Danny Sullivan, Google's public search liaison, Tweeted that Google uses CTR as a ranking signal.


Screenshot of Danny Sullivan's post about the importance of Click-Through-Rate, published on Twitter on March 2015.

It’s finally clear that click-through-rate leads to higher rankings and more traffic.


The bottom line is you want your website to generate rich snippets, because they are a key element for SEO.



The drawback of rich snippets: the zero-click search

Sometimes, Google uses rich snippets to match and satisfy users’ intent without the need of clicking any search results.


Agressive SERP features and instant answers decrease organic CTR.

The prominence of mobile search and the raising of voice search have moved users’ needs towards short and practical answers.

In 2019, Rand Fishkin, CEO and co-founder of SEOmoz, assembled Jumpshot’s clickstream data and discovered that organic CTR has dropped to 47.4%.


In the first quarter of 2019, 48.96% of all US Google searches captured by Jumpshot ended without a click.


Where users click after searching Google (Q1 2019). Notes: data from 1B+ searches on 10M+ US mobile and desktop devices. Searches and clicks based on US clickstream data, browser searches only, non-iOS devices, on Google.com.

Google doesn’t need structured data to generate rich results. In fact, it can pull information from your web page, re-elaborate them and put them back together in what Fishkin calls “aggressive SERP features and instant answers”.


Usually, zero-click searches include:

  • Database-related searches. When you search queries on dates, time and time zones, currency conversions, age and names of people and products…;

  • Dictionary and encyclopedia-related searches. When you use terms like “what is” and “definition of” in the search;

  • Map direction-related searches. When your search queries include words that prompt local results like “near me”, “vegan restaurant” and so on.


Despite rich snippets are commonly recognized as an opportunity to drive more new visitors and visibility, you lose traffic when users settle for the information found in the SERP.


The challenge for an SEO specialist is to be featured in the SERP with rich snippets that don’t provide a complete solution. In this way, users will have to visit your page to attain the information they need.





FREE SCHEMA MARKUP GENERATORS




If you want an easy and fast solution to add Schema markups on your website, I’ll show you some free tools I use to generate structured data.


Regardless of which tool you use, you will generate pretty much standardized markups. If you want to learn how to write tailored Schema markups in JSON-LD, skip this chapter.



Schema markup generator (JSON-LD) by Merkel

Schema Markup Generator (JSON-LD) is the free tool I prefer to create basic structured data. This tool was created by Max Prin, head of TechnicalSEO at Merkel Inc.


Free Schema Markup Generator (JSON-LD) by Max Prin from TechnicalSEO.

Through a drop down menu, you can choose a markup and input relevant data in an easy-to-use form.


They offer Microdata or JSON-LD Schema markups for many applications, including:

  • Website information;

  • Breadcrumb navigation;

  • Articles;

  • Product information;

  • Local business;

  • People;

  • Events;

  • Recipes;

  • Job postings.


Three reasons why you should use TechnicalSEO schema markup generator

  1. It is totally free and foolproof;

  2. It allows you to directly test the code on Google Structured Data Testing Tool or Rich Results Test;

  3. It doesn’t require any coding expertise and allows you to handle structured data autonomously without bothering a developer.


You can play around with this tool and when you are ready to add more personalization to your JSON-LD, you should try to make your own code using the official documentation on schema.org.



Structured Data Markup Helper by Google

Structured Data Markup Helper is Google's webmaster tool that allows you to visualize a web page and directly tag elements through a special editor.


When you are done tagging, Google generates the appropriate Schema markups and inserts them into the page’s HTML that you can download and re-upload into your website.


Select the type of structured data you want to generate. You can start with an URL or HTML code.


Screenshot of the enter page of Google Structured Data Markup Helper.

In the second step, Google replicates the page in its editor which you can use to tag relevant elements.


Screenshot of the tag data page of Google Structured Data Markup Helper. Select a piece of content on your web page and attribute a Schema markup with Google editor.

In the third and final step, Google replicates the page’s HTML with the new Schema markups included.


Download the code and re-upload it into your website accordingly.



Data Highlighter by Google

If you want to create structured data for yourself or for a website you own, I recommend to use Data Highlighter by Google.


This free SEO tool is part of Google Search Console and works almost like the Structured Data Markup Helper.


The main difference is that Data Highlighter directly installs in your website’s code the Schema markups.


In fact, if you check the upper right corner of the editor, you will find a button to publish the edits.


Screenshot of Google Data Highlighter editor in Search Console.

Data Highlighter also allows you to save your work in progress and store all of your pages with highlighted data.


In this way, you can always review and update your work or save a draft and finish it later.





HOW TO USE SCHEMA.ORG




From the homepage of schema.org, reach the section “Schemas” by using the menu in the header.


Screenshot of Organization of Schemas page on schema.org.

On this page, you can:

  • Select the most common Schema markups;

  • View the full markups list;

  • Use the search bar in the header to find the exact markup you are looking for.


Let’s say you want to add an Organization markup. As you can see from the image below, the documentation shows you three columns.


Organization markup reference page on schema.org.

The first column is a list of properties from the application selected. As we said, in this example we picked the application Organization. A property provides additional information to describe an application.


This list is in alphabetical order.


The second column indicates what you should write in the code for each property.


Address property reference for Schema structured data.

For example, when you add the property address, you can simply use a string of text to specify the address of your organization or use an expected type called PostalAddress.


Let’s say your organization is the Art Museum of Philadelphia, your address will be: “2600 Benjamin Franklin Pkwy, Philadelphia, PA 19130”.


If you see a “special” clickable element (expected type) in the second column, it means you can include an additional type to your markup.


When you create Schema structured data, you should be as specific as possible, so always use expected types when possible.


For instance, instead of associating just a string of text to the address property, click on PostalAddress to view its reference page and add more properties.


PostalAddress Schema markup reference page on schema.org.

As you can see, this page is very similar to the previous one, but it is about the type PostalAddress.


Here, you can find all the “sub-properties” you can use to describe the main property address.


At the end of the Organization page, you can find a list of Schema markup examples that you can use as a reference to write the actual code.


At the end of every structured data reference page on schema.org, you can find a list of Schema markup examples.




7-STEP STRUCTURED DATA WORKFLOW




In this chapter, I’ve described the workflow I use when I create personalized Schema structured data. You can use it as a brief handbook to smooth your SEO process.



Step 1: select a Schema application

According to your SEO needs, select one or more Schema applications for each web page.


To help you decide, just answer these two questions:

  1. What rich snippet do you want to generate?;

  2. What does search engines need to know to interpret the page correctly?.


I’ve listed below some of the most common Schema applications.


Review markup. It displays a star rating with a scale from 1 to 5 that can represent a single reviewer or an average of multiple users’ reviews (aggregate rating).


Example of Review rich snippet in Google's SERP.

Product markup. It gives information about a certain product and includes images, price and availability.


Example of Product rich snippet in Google's SERP.

Recipe markup. It displays information about the time to prepare a dish, reviews and recipe images.


Recipe rich snippet example in Google's SERP.

Event markup. It shows events’ dates, times, location and more.


Event rich snippet example in Google's SERP.

Organization markup. It helps search engines understand key information about a business, like address, logo and contacts.


Nike's Organization rich snippet in Google's SERP.

Music markup. It helps Google index music by providing info on genre, album, release dates, lyrics and so on.


Music rich snippet example in Google's SERP.

Video markup. Search engines can’t understand images, so they need structured data to interpret videos.


Video rich snippet example in Google's SERP.

Top stories markup. It gives a website the opportunity of appearing in the “Top Stories” box in the search results and it only applies to Google News’s approved websites.


Top stories rich snippet example in Google's SERP.


Step 2: find the related documentation on schema.org

Once you know the Schema applications to insert in your website, go on schema.org and use the search bar to find it.



Step 3: identify what properties you need to describe your Schema application

Go over the list in the first column and write down the properties that you need to describe your application.


Do the same with the expected types if any (“sub-properties”).



Step 4: start from the examples to generate your JSON-LD

Use the examples at the end of the page as a starting point to generate your JSON-LD structured data.



Step 5: validate your code

Copy and paste your JSON-LD in Google Structured Data Testing Tool and verify it doesn’t have errors.



Step 6: insert the JSON-LD markup in your web page HTML

According to Google documentation, you should insert JSON-LD Schema markups in the head section of your web page.


When you insert these kind of codes, you usually have two options (above all, if you use website builders like Wix):

  • Load the code once;

  • Load on each new page.


Choose to load the code once.


In September 2019, John Mueller stated on a video that Google can also process structured data inserted in the body section.


Depending on the specific markup, you might have different guidelines case to case.


For example, the Website markup must be inserted only in the head of the homepage.


The Corporation markup (or the broader Organization markup) can be inserted in the head of every page of your website. Nevertheless, other SEO experts recommend inserting it in the homepage or in pages where there is information about the company or the organization which owns the website (e.g. about or contact page).


Personally, I’ve inserted the Organization markup in every page, since it contains relevant information for branding and copyright.



Step 7: verify your code has no errors

Verify the structured data on your web page by pasting the URL in Google Structured Data Testing Tool or Rich Results Test.


The latter tests your publicly accessible page to see which rich results can be generated by the structured data it contains.


Screenshot of Google Rich Results Test.




UNDERSTANDING THE SYNTAX

OF JSON-LD




Before I show you how to create Schema structured data, I want to teach you some basic syntax of JSON-LD.


In this way, you will better understand the code in the workshop, because I won’t repeat the meaning of these symbols.



Curly braces

In between the opening and closing script tag, you find an open and closed curly brace.


<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Organization",
  "name": "",
  "url": "",
  "logo": ""
}
</script>

Structured data will be inserted in between these two curly braces. As you write your markup, you’ll probably add more curly braces. To keep things from getting too confusing, use indentation.


Remember that for each open brace (or bracket) you must have a closed one.



Schema type: “@type”

The keyword “@type” specifies the item type being marked up. You can find a comprehensive list of all item types here.


You use it at the beginning of the script when you state the type of the application and every time you need to add an expected type: an item from the second column of a schema.org reference page, to be clear.



Quotation marks

Whenever you call a Schema type, a property or fill in a field, you need to enclose the information in quotation marks.


<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Organization",
  "name": "Alberto Carniel",
  "url": "https://www.albertocarniel.com",
  "logo": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg"
}
</script>


Colons

Whenever you call a type or property, you need a colon to continue input information. In other words, colons are a field separator.



Commas

Imagine this code as a list of elements and, as every list requires, you need to place a comma after each element.


<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Organization",
  "name": "Alberto Carniel",
  "url": "https://www.albertocarniel.com",
  "logo": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg"
}
</script>

After the informational field for the logo property there is no comma, because it’s the last element and there is no additional information to be stated.



Brackets

Use brackets whenever you include a property with more than one item/entry. This is also called array.


<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Organization",
  "name": "Alberto Carniel",
  "url": "https://www.albertocarniel.com",
  "logo": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg",
  "sameAs": [
     "https://www.linkedin.com/in/albertocarniel/",
     "https://www.instagram.com/albertocarniel91/",
     "https://www.youtube.com/c/AlbertoCarniel",
     "https://twitter.com/CarnielAlberto"
  ]
}
</script>

In the property sameAs of the example above, I’ve enclosed my social media channels in brackets.


If I had only one social media profile, I would have listed just one URL without brackets.


Note that after my Twitter profile there is no comma, because it is the last element within the brackets. If there was another property after sameAs, I would have placed a comma after the closed bracket.



Inner curly braces

Use inner curly braces every time a property has an expected type (see the second column of a schema.org reference page).


<script type="application/ld+json">
{
  "@context": "http://schema.org/",
  "@type": "Organization",
  "name": "Alberto Carniel",
  "contactPoint": {
     "@type": "ContactPoint",
     "telephone": "+1 (631) 988-6773",
     "contactType": "customer service",
     "availableLanguage": ["English","Italian"]
     }
}
</script>

In the example above, I’ve called the property contactPoint which requires a type ContactPoint. That’s why it is enclosed in curly braces.


As you can see from the image below, the expected type is written in the second column. Click on the expected type link to view its reference page.


Structured data reference of the property "contactPoint" on schema.org.




HOW TO CREATE STRUCTURED DATA WITH JSON-LD (WORKSHOP)




In this chapter, I’ll show you how to use schema.org as a reference to write custom structured data in JSON-LD.


For this workshop, I’ve used the Organization markup as an example. You can replicate the following process and techniques to write different structured data as you please.


Disclaimer: I haven’t used indentation, since if you don’t have programs like NotePad++, it’s difficult to do it properly.


For my Schema structured data, I just use NotePad and save my JSON-LD in .txt format.


NotePad is already included in Windows. If you have a Mac, you can use TextEdit.


If you have a more professional text editor for coding, you are free to use it. You might need to adjust the syntax appropriately by tweaking the settings:


View > Syntax > JavaScript > JSON


This is the final Organization markup that we’ll create and it also represents the structured data I’m using on my website albertocarniel.com:


<script type="application/ld+json">
{
"@context": "http://schema.org/",
"@id": "https://www.albertocarniel.com/#organization",
"@type": "Corporation",
"name": "E-commerce and Digital Marketing Consultant | Alberto Carniel",
"alternateName": "Alberto Carniel",
"description": "Alberto Carniel is an international e-commerce and digital marketing consultant who serves public and private businesses operating in the US and Italian markets",
"url": "https://www.albertocarniel.com/",
"logo": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg",
"email": "alberto@albertocarniel.com",
"foundingDate": "2016-04-17",
"sameAs": [
"https://www.linkedin.com/in/albertocarniel/",
"https://www.instagram.com/albertocarniel91/",
"https://www.youtube.com/c/AlbertoCarniel",
"https://twitter.com/CarnielAlberto"
],
"aggregateRating": {
"@type": "AggregateRating",
"bestRating": "5",
"ratingValue": "5",
"worstRating": "1",
"reviewCount": "30"
},
"address": [{
"@type": "PostalAddress",
"addressCountry": "USA",
"addressLocality": "Dix Hills",
"postalCode": "XXXXX",
"streetAddress": "XXXXXXXXXXXXXXX"
},
{
"@type": "PostalAddress",
"addressCountry": "ITA",
"addressLocality": "Albignasego",
"postalCode": "XXXXX",
"streetAddress": "XXXXXXXXXXXXXXX"
}
],
"contactPoint": [{
"@type": "ContactPoint",
"telephone": "+1 (631) 988-6773",
"contactType": "customer service",
"availableLanguage": ["English","Italian"]
},
{
"@type": "ContactPoint",
"telephone": "+1 (631) 988-6773",
"contactType": "sales",
"availableLanguage": ["English","Italian"]
}
],  
"founders": {
"@type":"Person",
"name": "Alberto Carniel",
"image": "https://static.wixstatic.com/media/2686e0_dc02f9490e4c4e0da5499b32d384c542~mv2.jpg",
"birthPlace": "Padua, Italy",
"birthDate": "1991-10-28",
"gender": "Male",
"nationality": "Italian",
"email": "alberto@albertocarniel.com", 
"jobTitle": "E-commerce and Digital Marketing Consultant",
"sameAs": [
"https://www.facebook.com/alberto.carniel.9",
"https://www.instagram.com/albertocarniel91/",
"https://www.linkedin.com/in/albertocarniel/",
"https://www.youtube.com/c/AlbertoCarniel",
"https://twitter.com/CarnielAlberto"
]
}
}   
]
}
</script>

This Organization markup includes the following properties:

  • Type;

  • Id;

  • Name;

  • Alternate name;

  • Description;

  • URL;

  • Logo;

  • Email;

  • Founding date;

  • Social media channels;

  • Aggregate rating;

  • Multiple business’s addresses;

  • Contact points;

  • Founders.


Let’s begin.



Workshop: how to create the Organization Schema markup in JSON-LD

In this section, I’ll explain to you how to write each line of the previous code, and where to retrieve vocabulary and syntax for each element.


If you want to use this Organization markup in your own website, just substitute my information with yours.


Disclaimer: I’m not a developer, so I’m teaching you exactly the way I’ve learned as a self-taught person.


If you want to become independent in writing JSON-LD Schema markups, I recommend practicing a lot and testing your codes on Google Structured Data Testing Tool. The latter will describe eventual errors, so that you can correct your code and try again.


To better organize this section, I’ve divided each part of the code with a page separator.



<script type="application/ld+json">
{
"@context": "http://schema.org/",

This is how the JSON-LD code begins (opening script tag).


There is nothing to understand, just copy and paste this snippet every time you start creating Schema structured data.



"@id": "https://www.albertocarniel.com/#organization",

This line represents a node identifier: it allows you to attribute a URI (Uniform Resource Identifier) to a node.


Just to keep it simple: consider a URI as an URL (if you want to know the difference, read this document) and a node as a container of information.



In JSON-LD, “@id” indicates a node and


https://www.albertocarniel.com/#organization

is the URI.



A node and a URI together form an IRI (Internationalized Resource Identifier).


In layman terms, with this string:


"@id": "https://www.albertocarniel.com/#organization",

you are saying that all the other following strings (the other properties of the Organization markup) refers to a “fictional” page identified by the URI:


https://www.albertocarniel.com/#organization

This URI represents the actual organization and not a page (or a part of that page) about the organization.


We are distinguishing the thing from the page about the thing.


In this example, the thing is Alberto Carniel as a business/organization.


Instead, the page about the thing is just the domain “albertocarniel.com”, since it is Alberto Carniel’s homepage.


Let’s change the example.


Pretend we are in a discussion about Apple.


If I refer to Apple by using:


https://www.apple.com/#organization

I refer to it as a brand/organization.


If I refer to Apple by using "https://www.apple.com”, I’m just mentioning its website homepage.


You can find the documentation on schema.org under the property identifier.


Structured data reference of the property "identifier" on schema.org.

If you click on background notes, it is explained that when you want to write a string with an identifier, you should use:

  • “Itemid” if you use Microdata;

  • “resource” if you use RDFa 1.1;

  • “@id” if you use JSON-LD.


Background information of the "identifier" property on schema.org.

A node identifier is very useful to call a complete markup without the need of re-writing it.


For example, you can connect your Organization markup with your Website markup by using the string:


"isPartOf": {"@id": "https://www.albertocarniel.com/#organization"}

Adding this string to the Website markup, you are saying that your website is part of your organization (remember the comma at the end if it is not the last element).


Example of node identifiers used by Yoast in their WordPress SEO definitive guide:


<script type="application/ld+json">
{"@context":"https://schema.org",
"@graph":[
{
"@type":"Organization",
"@id":"https://yoast.com/#organization",
"name":"Yoast",
"url":"https://yoast.com/",
"sameAs":
["https://www.facebook.com/yoast",
"https://www.instagram.com/yoast/",
"https://www.linkedin.com/company/1414157/",
"https://www.youtube.com/yoast",
"https://www.pinterest.com/yoast/",
"https://en.wikipedia.org/wiki/Yoast",
"https://twitter.com/yoast"],
"logo":{"@type":"ImageObject",
"@id":"https://yoast.com/#logo", 
"url":"https://yoast.com/app/uploads/2015/09/Yoast-Logo-Icon-120x120.png",
"caption":"Yoast"},
"image":{"@id":"https://yoast.com/#logo"}},
{
"@type":"WebSite",
"@id":"https://yoast.com/#website",
"url":"https://yoast.com/",
"name":"Yoast",
"publisher":{"@id":"https://yoast.com/#organization"},
"potentialAction":{"@type":"SearchAction",
"target":"https://yoast.com/?s={search_term_string}",
"query-input":"required name=search_term_string"}},
{
"@type":"WebPage",
"@id":"https://yoast.com/wordpress-seo/#webpage",
"url":"https://yoast.com/wordpress-seo/",
"inLanguage":"en-US",
"name":"WordPress SEO Tutorial \u2022 The Definitive Guide \u2022 Yoast",
"isPartOf":{"@id":"https://yoast.com/#website"},
"image":{"@type":"ImageObject",
"@id":"https://yoast.com/wordpress-seo/#primaryimage",
"url":"https://yoast.com/app/uploads/2008/04/WordPress_SEO_definitive_guide_FI.png",
"caption":""}, 
"primaryImageOfPage":{"@id":"https://yoast.com/wordpress-seo/#primaryimage"},
"datePublished":"2019-03-28T14:05:01+00:00",
"dateModified":"2019-04-11T12:24:14+00:00",
"description":"This is the ONLY tutorial you'll need to hugely increase your search engine traffic by improving your WordPress SEO. Want higher rankings? Read on!",
"breadcrumb":{"@id":"https://yoast.com/wordpress-seo/#breadcrumb"}},
{
"@type":"BreadcrumbList",
"@id":"https://yoast.com/wordpress-seo/#breadcrumb",
"itemListElement":[
{
"@type":"ListItem",
"position":1,
"item":
{"@type":"WebPage",
"@id":"https://yoast.com/",
"url":"https://yoast.com/",
"name":"Home"}},
{
"@type":"ListItem",
"position":2,
"item":{"@type":"WebPage",
"@id":"https://yoast.com/seo-blog/",
"url":"https://yoast.com/seo-blog/",
"name":"SEO blog"}},
{
"@type":"ListItem",
"position":3,
"item":{"@type":"WebPage",
"@id":"https://yoast.com/tag/wordpress/",
"url":"https://yoast.com/tag/wordpress/",
"name":"WordPress"}},
{
"@type":"ListItem",
"position":4,
"item":{"@type":"WebPage",
"@id":"https://yoast.com/wordpress-seo/",
"url":"https://yoast.com/wordpress-seo/",
"name":"WordPress SEO: the definitive guide"}}]},
{
"@type":"Article",
"@id":"https://yoast.com/wordpress-seo/#article",
"isPartOf":{"@id":"https://yoast.com/wordpress-seo/#webpage"},
"author":{"@id":"https://yoast.com/about-us/team/joost-de-valk/#author",
"name":"Joost de Valk"},
"publisher":{"@id":"https://yoast.com/#organization"},
"headline":"WordPress SEO: the definitive guide",
"datePublished":"2019-03-28T14:05:01+00:00",
"dateModified":"2019-04-11T12:24:14+00:00",
"commentCount":"4",
"mainEntityOfPage":"https://yoast.com/wordpress-seo/#webpage",
"image":{"@id":"https://yoast.com/wordpress-seo/#primaryimage"},
"keywords":"Content SEO, Google Analytics, Mobile SEO, Security, Site Speed, Site Structure,
Technical SEO, WordPress, Yoast SEO"},
{
"@type":"Person",
"@id":"https://yoast.com/about-us/team/joost-de-valk/#author",
"name":"Joost de Valk",
"image":{"@type":"ImageObject",
"@id":"https://yoast.com/#personlogo",
"url":"https://yoast.com/app/uploads/2018/09/avatar_user_1_1537774226.png",
"caption":"Joost de Valk"},
"description":"Joost de Valk is the founder and Chief Product Officer of Yoast and the Lead
Marketing & Communication for WordPress.org. He's a digital marketer, developer and an Open Source fanatic.",
"sameAs":[
"https://www.facebook.com/jdevalk",
"http://www.linkedin.com/in/jdevalk",
"https://twitter.com/jdevalk"]}
]}</script>

Basically, they stated that the Article belongs to a certain WebPage that belongs to the Yoast Website that belongs to the Yoast Organization.



"@type": "Corporation",

With this string, we are stating the application type. It is also valid to write:


"@type": "Organization",

Corporation is just a more specific type of organization. In fact, if you scroll the page, you’ll find the related reference.


More specific types of organization on schema.org.

If you are a local business, and want to further specify your category, but don’t find the right terminology on schema.org, you can add your business category here: just follow the instructions on the page.



"name": "E-commerce and Digital Marketing Consultant | Alberto Carniel",

This string represents the name of your organization. Just copy and paste the property as it is from the first column and enclose it in quotation marks.


Structured data reference of the property "name" on schema.org.

In the second column, it is said you can use Text as a value, so just write the name of your business by enclosing it in quotation marks.



"alternateName": "Alberto Carniel",

This string represents an alias or an alternative name that is used to call your organization.


Structured data reference of the property "alternateName" on schema.org.


"description": "Alberto Carniel is an international e-commerce and digital marketing consultant who serves public and private businesses operating in the US and Italian markets",

Provide a full description of your organization. The property description is very useful to insert relevant keywords for the business.


Structured data reference of the property "description" on schema.org.


"url": "https://www.albertocarniel.com/",

Provide the URL of the organization. Usually, it is the homepage.


Structured data reference of the property "url" on schema.org.


"logo": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg",

If you check the second column of the logo, you can insert an URL or the expected type ImageObject.


Structured data reference of the property "logo" on schema.org.

In this case, I just inserted the URL of my logo image, but if you want to be more precise, you click on ImageObject and add its properties.


If you want to insert an ImageObject instead, this is a JSON-LD example:


"logo": {
"@type": "ImageObject",
"keywords": "Alberto Carniel, logo, signature, digital marketing consultant logo",
"url": "https://static.wixstatic.com/media/2686e0_ce8b0e616edc4c2e90ce339361cd9bed~mv2.jpg",
"creator": {
"@type": "Person",
"givenName": "Alberto",
"familyName": "Carniel"
}
},

Use the ImageObject reference page to add additional properties. In this example, the property creator has an expected type called Person.


Structured data reference of the property "creator" on schema.org.

Again, click on Person and view the related properties. The process is always the same.


Remember to close all the opened curly braces at the end.



"email": "alberto@albertocarniel.com",

This field is very easy, from the Organization reference page copy and paste the property email and write the email address of your organization.


Structured data reference of the property "email" on schema.org.


"foundingDate": "2016-04-17",

As you can see from the second column, the property foundingDate has an expected type Date, but we didn’t use the keyword “@type” for this string.


Let’s understand why.


Structured data reference of the property "foundingDate" on schema.org.

Click on Date and land on its reference page. Here you have two choices:

  1. You can insert properties of Date, but you need to use the keyword “@type” and structure the string like in the previous example about ImageObject;

  2. You can just write a date value in ISO 8601 date format.


Use the ISO 8601 date format for structured data.

Just click the link and you will land on a page of Wikipedia where it is explained how to write a date in an international format.


In my example I placed Year-Month-Day.



"sameAs": [
"https://www.linkedin.com/in/albertocarniel/",
"https://www.instagram.com/albertocarniel91/",
"https://www.youtube.com/c/AlbertoCarniel",
"https://twitter.com/CarnielAlberto"
],

Here we are at the first array.


There is no property named socialMedia, communicationChannel or something similar. If you want to add other web pages that unequivocally represent the identity of your organization, you should use the property sameAs.


Structured data reference of the property "sameAs" on schema.org.

After all, social media profiles are web pages that represent your organization, so they are perfectly part of this property.



"aggregateRating": {
"@type": "AggregateRating",
"bestRating": "5",
"ratingValue": "5",
"worstRating": "1",
"reviewCount": "30"
},

In my Organization markup, I’ve decided to insert the property aggregateRating, because it represents an average of your reviews (or rating, it depends on which property you use).


Structured data reference of the property "aggregateRating" on schema.org.

Click on aggregateRating and land on its reference page.


Usually, reviews rating is expressed on a scale from 1 to 5 and Google generates the rich snippet with the “five stars”.


If the maximum score you can get is 5 and the minimum is 1, insert the value “5” in the bestRating field and “1” in the worstRating field.


Add up your reviews and insert the value in the reviewCount field. I counted my reviews on Yelp!, Google, LinkedIn, Facebook, UpCity and Clutch.


If you want a rich snippet to appear, I would add on your web page an image with the stars to represent your average rating and a text that explains where the data comes from.


Alberto Carniel aggregate rating. Retrieved 13 June 2020.


"address": [{
"@type": "PostalAddress",
"addressCountry": "USA",
"addressLocality": "Dix Hills",
"postalCode": "XXXXX",
"streetAddress": "XXXXXXXXXXXXXXX"
},
{
"@type": "PostalAddress",
"addressCountry": "ITA",
"addressLocality": "Albignasego",
"postalCode": "XXXXX",
"streetAddress": "XXXXXXXXXXXXXXX"
}
],

The address property can become a complex array for businesses with multiple locations.


In the second column we see that we can insert Text or the expected type PostalAddress. You should always be super precise, so go ahead and add the expected type.


Structured data reference of the property "address" on schema.org.

Click on PostalAddress, view its reference page and add relevant properties.


The important part to remember when you write this array is to open a bracket before the curly brace:


"address": [{

That bracket indicates a list. Enclose each item in curly braces and close the bracket at the end of the list.


For the property addressCountry, take a peek at ISO 3166-1 alpha-2 country code: you can select a country code with two or three letters according to the international standards.


If your organization is a local business, you can add the geographic coordinates of your location. Sometimes, search engines are not so precise with just an address.


How many times have you tried to reach a destination, but Google Maps is not able to find it accurately?


To do this, use the localBusiness markup, instead of Corporation/Organization. To be clear, when you open the JSON-LD script you’ll have something like:


<script type="application/ld+json">
{
"@context": "http://schema.org/",
"@id": "https://www.example.com/#organization",
"@type": "localBusiness",

Add both the address and geo property of your business. This is an example of geo property (the coordinates are about the Art Museum in Philadelphia):


"geo": {
"@type": "GeoCoordinates",
"latitude": "39.965507",
"longitude": "-75.180859"
},

As promised, now I will explain to you where you find the syntax of this JSON-LD.


If you scroll down the postalAddress reference page you can find a section stating you may find the address as a property for the type GeoCoordinates.


Structured data reference of the "GeoCoordinates" type on schema.org.

Click on GeoCoordinates and scroll down its reference page till you find the section stating that you can find instances of GeoCoordinates in the property geo.


Structured data reference of the "Geo" property on schema.org.

In the second column there is written that geo is a property of the type Place. Click on Place and scroll down its reference page. You will find a list of more specific types.


More specific types of "place" on schema.org.

From this list, you clearly understand that localBusiness is considered a specific type of Place. It means that a localBusiness is considered both a Place and an Organization.


In other words, if you create a localBusiness markup you can use the geo property. Here is a basic example of localBusiness JSON-LD markup:


<script type="application/ld+json">
{
"@context": "http://schema.org/",
"@id": "https://www.example.com/#organization",
"@type": "localBusiness",
"name": "Example",
"address": {
"@type": "PostalAddress",
"addressCountry": "USA",
"addressLocality": "Example",
"postalCode": "XXXXX",
"streetAddress": "XXXXXXXXXXXXXXX"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": "39.965507",
"longitude": "-75.180859"
},
"image": "business-main-image.jpg",
"telephone": "1234567890",
"priceRange": "$$$"
}
</script>

Some properties are mandatory for certain applications. For instance, a localBusiness markup requires the property name, address, image, telephone and priceRange.


Note: always test your JSON-LD with Google Structured Data Testing Tool. As long as you don’t receive any error message, your markup will work.


How can you retrieve the geographic coordinates of a place?


On desktop, write the address of a place on Google Map and click on its exact location. It will pop a small image with the coordinates that you can copy and paste in your Schema markup.


Geographic coordinates of the Art Museum (Philadelphia, PA) on Google Maps (desktop version).

On mobile, follow the same procedure and hold your finger on the exact location of your place. After having dropped the pin, you can read the coordinates in the search bar.


Google Maps screenshot of the Art Museum (Philadelphia, PA) geographic coordinates (mobile version).


I think I’ve covered all the tricky parts of the Organization markup and I hope you are now capable of creating any custom Schema markups by yourself.


This workshop ends here, but if you have any questions, feel free to comment below.





CONCLUSIONS




Schema structured data is fundamental for SEO and you should implement JSON-LD in the HTML of your web pages whenever possible.


Creating JSON-LD structured data is like a treasure hunt, since it’s very unlikely to remember every single Schema type and property invented.


Writing custom Schema markups is not easy and requires time to exercise and a lot of testing.


I’ll be happy to review your JSON-LD snippets if you need help. So, feel free to drop your requests in the comments below!



© 2020 by Alberto Carniel. All rights reserved. Privacy Policy.

Alberto Carniel's black logo on a transparent background.