Bonus: You can reference more than one data blob in the same itemref attribute! Just add them one after the other, separated by spaces.
E.g., itemref=”comments wordcount citation alternativeHeadline”
Boom! Now you’re cooking with itemref! Where before you had a pantry full of data that didn’t really go together, now you have an entity that is completely baked and you’re ready to roll.
How to use itemid
Using itemid is actually very similar and may even involve less new code than itemref. Since you use itemid when you want to reference another complete entity, this might be an entity that’s already on the page. If that’s the case, you just add a quick bit of markup and you’re good to go.
In the visual below, what we want to do is use the Secondary Entity to populate an itemprop of the Primary Entity.
Using our blog post example, let’s say we want to reference an Organization entity to populate the publisher itemprop of the BlogPosting entity.
Here’s how we do that:
Step 1: Mark up the Secondary Entity just as you normally would. If you already have that entity on your page and it’s fully marked up, that’s less work for you!
Step 2: In the opening itemscope/itemtype declaration of that entity, add an itemid attribute and give this secondary entity a unique fragment identifier.
It should look like this:
And now we make the magic happen!
Step 3: Within your Primary Entity, add a tag wherever you want to call in the Secondary Entity and specify the itemprop you want your Secondary Entity to populate. Use a simple href attribute to point to the fragment identifier from Step 2.
It should look like this:
Bonus: You can reference this secondary entity from multiple other entities and populate multiple itemprops, too! If this post were a company announcement on moz.com and Moz were both the publisher and the author, both of those properties could reference #mozOrg.
That’s it! Now, regardless of where these two entities live in the DOM (i.e., in your page’s source code), they’ll be linked together and can create something awesome.
“By your powers combined, I am a great blog post!”
Extending the power of itemid to JSON-LD
I can hear some readers asking, “The days of microdata are over! Now that Google’s going to support JSON-LD for everything, who cares?”
First, Google isn’t the only game in town and they don’t yet support JSON-LD for all Schema.org types (but, honestly, I think they will soon). That said, I still think it’s good practice to continue implementing structured data that less evolved crawlers can use.
Second, even though itemref can’t be used within the JSON-LD data model, itemid most definitely can, although in JSON-LD the property is called @id! And boy, does it come in handy.
Let’s talk about why you would use this and then we’ll get into how.
Why @id is great with JSON-LD
The why is pretty straightforward – just like when you’re using microdata, you are likely to have multiple JSON-LD entities on your site and, quite frequently, these will be housed in different scripts in the source code (or in different tags delivered via a tag management tool). Using @id, you can maintain your JSON-LD for each semantic entity separately and just make references between each entity as needed.
For example, consider the blog post you’re currently reading which has structured data for a BlogPosting delivered in JSON-LD. You could avoid having to include all the data for your publisher (the Organization known as Moz) in your JSON-LD script and instead reference a dedicated JSON-LD script for it.
You could host two independent JSON-LD scripts in your page and link them using @id.
In this example, using @id is more cool than useful; it doesn’t save that much time or effort. In fact, it’ll add a bit more code to the page if you’re including two separate JSON-LD scripts (for a BlogPost and an Organization) on every page rather than doing it all in one tag.
Dealing with repetition
But what about when a single entity can be used to populate multiple properties in your JSON-LD? That’s where @id could save you a ton of time and hassle.
Imagine you have an Article page where you want to include structured data about the article’s publisher (#publisher), a video pertaining to the article (published by #publisher), and the article’s author (who worksFor #publisher). Suddenly, having the ability to leverage a single definition of the Publisher entity is very valuable!
If you’re not already sold on @id yet, here’s where it gets crazy. When you use @id with JSON-LD, you can extend its utility massively.
You can use @id in a JSON-LD script to reference
entities on other pages and even other websites!
Let that sink in.
What this means is that you can deliver JSON-LD on every blog post that references an Organization JSON-LD tag on the homepage. You don’t need to repeat that data on each page or update every instance if a datapoint ever changes.
Here are just a few use cases in which you’d want to host JSON-LD for specific entities in centralized locations and reference them throughout your whole site.
- Hosting your Organization JSON-LD on your company homepage and then using it as:
- The publisher property on BlogPostings
- The worksFor property on Person (on your team profiles)
- Hosting Person JSON-LD for key personnel on your About page and then using those entities as:
- The author properties on BlogPostings
- The performer properties on Events
- (If you’re a local business) Hosting Place JSON-LD about your city on a dedicated landing page and using it as:
- The areaServed property on LocalBusiness
- The eligibleRegion property on Offer
- The foundingLocation property on Organization
- The jobLocation on property JobPosting
With all of these scenarios, you can use @id to reference entities on other pages to create a literal web of linked data on your website!
How to use @id in JSON-LD
Here’s how to use @id in your JSON-LD.
Step 1: Edit your JSON-LD and give the entity a fragment identifier (e.g., #eru). This uses essentially the same format as the @type property, so you pretty much just copy that. Repeat this process for every JSON-LD script that defines an entity that you want to be able to reference.
The modification to your JSON-LD should look something like this.
Step 2: In order to reference one of those entities from JSON-LD on another page, provide an @id in the place of a value for the property in question. For example, instead of just providing a text string of “Moz” for the “publisher” on this BlogPosting, we’d refer to the uniquely identified entity by using its @id.
The modification to your JSON-LD would look a bit like this:
Now, if the entity you’re pointing to lives on a different page, just use the absolute path rather than the relative one. “#mozOrg” becomes “https://moz.com/#mozOrg”
But wait. There’s more!
This is the part that really blew my mind. Remember that you can reference entities not just on your own website, but on OTHER websites as well. Doing so is really simple, though you do need to have the ability to slightly modify the JSON-LD on both sites.
The possibilities here are insane! Just picture the semantic associations we’re forming on this post alone!
The good news
The process is exactly the same as what’s described above (using @id on your own website), but you definitely need to use the absolute path.
The bad news
This is super hard to validate without building your own web crawler. By their nature, the structured data validation tools that are available to us (like Google’s Structured Data Testing Tool, the Structured Data Linter, or Yandex’s Structured Data Validator) only fetch the one URL that they’re fed. They’re not going to go out and crawl the URLs where the other linked data lives and show you the full picture that their crawlers may be able to get.
In the future, I’m hoping to share concrete proof that Google recognizes linked structured data across domains. Until then, the more cross-site structured data we create, the better our chances are of showing that this works!
Itemref & itemid in action
This wouldn’t be a very good tutorial if it didn’t leave you with something to fiddle with. The code example below will show you how to use itemref in microdata, itemid in microdata, @id to reference entities on the same page, @id to reference entities on other pages (hint: there may be a really cool entity over at https://moz.com/rand/about/#rand if you want to check it out), and @id to reference entities on other websites.
See the Pen The Search Marketer’s Guide to Itemref & Itemid by UpBuild (@upbuild) on CodePen.
You can even run this example’s URL through the Structured Data Testing Tool to see how Google interprets all the associations. Click here to see!
Until we meet again
I hope that this post has either given you some new tools that will help solve your structured data problems or has stoked your curiosity to see what’s possible with advanced JSON-LD. Good luck out there and happy optimizing!
“headline”: “The Search Marketer’s Guide to Itemref & Itemid”,
“description”: “This post is about giving you a new tool to add to your semantic SEO tool belt. My goal is to help you implement semantic markup and structured data with greater ease and enable you to create a more robust and complete web of linked data on your website (and beyond).”,
Sign up for The Moz Top 10, a semimonthly mailer updating you on the top ten hottest pieces of SEO news, tips, and rad links uncovered by the Moz team. Think of it as your exclusive digest of stuff you don’t have time to hunt down but want to read!