Schema.org is hard; we’re making it easy

Getting a Schema.org implementation right on a website was – until today – enormously painful. There was not enough documentation and no good tools to help you to make it truly simple. The best implementations so far really are, sadly, still just a fragmented mess. Today, we’ve fixed that.

The best Schema.org implementations we see ‘in the wild’ often look something like this, when seen by Google’s Structured Data Testing Tool:

Fragmented Schema.org markup, showing disparate, unconnected entities

There are seven Schema pieces on that page, but they’re just that: seven pieces without context. It is not clear what their relation to each other is. To a search engine, this page is still a puzzle which needs solving.

In our implementation, which we’re releasing today, all of the pieces “stitch together”: we form them into a nested structure. Without this nesting, a search engine doesn’t know how all these pieces relate to each other, and what the most important piece on a page is. Our implementation also clearly and explicitly defines the “main thing” on that page. This removes all of the guesswork and adds a lot of context for search engines.

Let’s look at an example: a post here on Yoast.com. This post is an Article. The article is the main “thing” of a WebPage, which is part of a Website. This Article is published by an Organization and written by an Author. Both the Author and the Organization have social profiles attached to them. These separate blocks are now all woven together: it’s simply a nested structure.

The @id is the glue

The secret of our delicious graph is one simple “thing”: using @id to connect graph pieces to each other. We output separate pieces but by using those @id references, we connect them to each other.

Because we can nest them like that, it doesn’t have to stop at that simple structure: the WebPage has a position within the site, outlined by its BreadcrumbsList. The Author, the Organization and the Article have images. Etc. etc. etc. All of that data is combined.

Why did we develop this?

We didn’t just start implementing this for the fun of it. We are solving a real-world problem: as more and more people implement Schema.org markup, the situation shown in the screenshot at the top of this article is no longer unique. Lots of pages, with lots of separate Schema blocks, are a problem. In a call with Pinterest recently one of their engineers complained: all the Schema that WooCommerce put out was nice, but when there are related products on a page, they often can’t find the main product. Our implementation solves that and many other problems.

On every page, we output the entire graph for that page, and we clearly mark the mainEntity, so Google, Pinterest, and others are no longer left guessing. Every relationship is made explicit.

What do these changes mean for you?

This change has short-term implications: you have a higher chance of getting:

  • Correct info in Google Knowledge Panels and full support for Rich Article Pins on Pinterest, due to better Schema output from Yoast SEO.
  • Showing up in a News listing or carousel if you use our News SEO plugin, due to the new NewsArticle support.
  • Higher chance of product snippets in Google Search results if you use our WooCommerce SEO plugin and full support for Rich Product pins on Pinterest, due to better Product support in it.
  • Higher chance of good local listing snippets, due to better LocalBusiness schema in our Local SEO plugin.

Long term implications for the web

These changes also have long term implications: we weave a web of data. This type of machine-readable data makes it possible for platforms to build much cooler things. And we wouldn’t be Yoast if we didn’t do this all out in the open. We have a full set of developer documentation on how to do this, and how to interact with our Schema API. Everyone can integrate with this, everyone can build upon it; in fact, we encourage you to do that!

We’ve also documented all our output, so you can learn from it, copy it, play with it. The specification document explains it all more in-depth and explains all the fantastic research that Jono has been doing in this.

I’m deeply excited about this change and think it’s the start of something really big. Now, go upgrade to Yoast SEO 11.0 and check it out!

Read more: Yoast SEO 11.0: Structured data awesomeness »

Take your technical SEO to the next level

  • Get Technical SEO & Structured data training
  • Hands-on advice for your technical setup
  • Save $$ by buying both Yoast courses
  • Start online when you are ready for it
More info

58 Responses to Schema.org is hard; we’re making it easy

  1. Kameron
    Kameron  • 8 months ago

    Wondering why you don’t add multiple crops to the image object for your in your webpage object on articles like google suggests https://developers.google.com/search/docs/data-types/article

    {
    “@context”: “https://schema.org”,
    “@type”: “NewsArticle”,
    “image”: [
    “https://example.com/photos/1×1/photo.jpg”,
    “https://example.com/photos/4×3/photo.jpg”,
    “https://example.com/photos/16×9/photo.jpg”
    ]
    }

    Also wondering how your image inside the webpage object would change if it were to have multiple crops. Would url just become an array of url’s pointing to each crop?

    {
    “@type”: “ImageObject”,
    “url”: [
    “https://example.com/photos/1×1/photo.jpg”,
    “https://example.com/photos/4×3/photo.jpg”,
    “https://example.com/photos/16×9/photo.jpg”
    ]
    etc….
    }

    One final question, would you recommend adding all of the images inside an article into the images array in the webpage object? or would we add those to the article object?

    Thanks!

    • Jono Alderson
      Jono Alderson  • 8 months ago

      Hi Kameron, great question!

      Because themes/plugins often make changes to the image sizes available on a site, it’s hard for us to define general/perfect rules for how this should behave. E.g., what happens if your site defines 20 custom crops? Should we output all of those? That might have performance implications, and quality implications.

      If you’re confident making the changes yourself, though, I’d definitely adding the extra images!

      You’d need to tweak your approach a little, and have an array of imageObjects, each with full meta data.

      E.g.,
      {
      "@type": "NewsArticle",
      "image": [{
      "@type": "ImageObject",
      "url": "http://www.example.com/image1.jpg",
      "caption": "Example Caption 1"
      },{
      "@type": "ImageObject",
      "url": "http://www.example.com/image2.jpg",
      "caption": "Example Caption 2"
      }]
      }

      As to whether those should be applied to the webPage or Article, that’s going to depend on your context, and, some editorial decisions, based on which you think the image ‘belongs’ to! That should *probably* be the most specific container they’re in – i.e., the article in this case.

      • Kameron
        Kameron  • 8 months ago

        Thanks! Great info, really appreciate you taking the time to demystify some of this json ld setup. My site has fallen squarely into the “best case scenario” you laid out above and I am excited to see how connecting this data works out.

  2. Denis
    Denis  • 8 months ago

    This is great, but what if I reviewed a product. How do I get the schema to show in Google of a 4 star review by x.

  3. Louie Bernstein
    Louie Bernstein  • 8 months ago

    I use WP SEO Structured Data Schema Pro. Will the new Yoast schema conflict with WP SEO?

    • Jono Alderson
      Jono Alderson  • 8 months ago

      Hey Louie,

      It’s best to check and test on your site, which you can do with Google’s Structured Data Testing tool (at https://search.google.com/structured-data/testing-tool/u/0/).

      Because both plugins work differently and do different things, some of that *might* overlap, and that might cause some problems. Best to run it through the tool, and see how Google sees your page, then make some decisions on how you want to change/fix your setup if there are issues!

  4. Hari
    Hari  • 8 months ago

    Thank you for the update, I have a question though, do I need to buy the news SEO plugin if we have a blog on our site to get better chance showing up in news article carousel? or the premium version already covered this?

    • Jono Alderson
      Jono Alderson  • 8 months ago

      Hey Hari,

      You’ll need the News plugin for specific optimisations for News articles, including a News XML sitemap, and, some news-specific Schema code.

  5. David
    David  • 8 months ago

    Awesome news, Yoast!

    How is schema data added by other 3rd-party plugins affected, i.e. if we use the “Schema – All In One Schema Rich Snippets” plugin (https://wordpress.org/plugins/all-in-one-schemaorg-rich-snippets/) or the “Schema” plugin (https://wordpress.org/plugins/schema/) does Yoast optimize that data as well?

    Thanks!

    • Joost de Valk

      Nope, we don’t touch it either so as long as it’s not conflicting with ours, it shouldn’t be too much of a problem. But I honestly think you won’t need those in the long run.

  6. apkdodo
    apkdodo  • 8 months ago

    Updating schema is not an easy task. As problem comes to update the number of reviews being given and that get’s updated simultaneously on SERP. Will try this trick and check if it works then very good.

  7. Sajjad Ahmad
    Sajjad Ahmad  • 8 months ago

    Indeed really good Yoast.
    How this will work for real estate website with property listings and agents listings?
    I am using Schema Pro for my website along with Yoast SEO Premium. Do I need to uninstall Schema Pro?

  8. Brittni
    Brittni  • 8 months ago

    Hello,

    How do I view this in Yoast? Is there a way to add schema markup using the Yoast tool? Also, is there a way to see whether or not schema has been added correctly?

    • Joost de Valk

      You can’t add schema manually, it’s all done automatically. The way to see that it’s been added is using Google’s Structured Data Testing Tool.

  9. Andi
    Andi  • 8 months ago

    “Article” schema shows errors when we select the site representative as a Person, and it must be an Organization. Google does not allow Person as the Publisher for articles. What to Do?

    • Joost de Valk

      It’s valid Schema markup, it’s just that Google’s Structured Data Testing Tool doesn’t like it. I wouldn’t worry about it for now and know that we’re discussing this with them.

  10. Raza Kazmi
    Raza Kazmi  • 8 months ago

    The most-awaited update has finally become functional. I’ve had manifold problems in building a proper structured-data of website using Google Webmaster Tools through its tutorials, but cannot successfully implement the structured-data of website. Nonetheless, with this update No More Worrying about it.

    Keep it up Yoast!

  11. DarkAllMan
    DarkAllMan  • 8 months ago

    Excellent work! Very happy with this update.
    I started checking and the amount of added data is immense.

    I do however still see warnings in the data testing tool:
    “Er ontbreekt een algemene ID voor dit product (zoals isbn, mpn of gtin8). Bekijk de documentatie voor geldige ID’s.”

    How would we as a store, that personalizes products, solve this?

    • Joost de Valk

      You won’t, unfortunately.

      • Randall Kam
        Randall Kam  • 8 months ago

        ok, so what does google want for an ID? (btw, I sent a support mail for this)

        • Joost de Valk

          It’s not an error, but a warning. If your products don’t have any of those types of ideas, it’s really impossible to fix it as far as I know.

  12. prasad
    prasad  • 8 months ago

    Thanks ‘Yoast SEO’

  13. Smith
    Smith  • 8 months ago

    Thanks for sharing the information with us, it was very informative.

    Yoast is the best seo plugin.

  14. Richard Hearne
    Richard Hearne  • 8 months ago

    The nesting and use of # fragments for IDs is very elegant. One thing I’m curious about is that the implemented JSON-LD on this page has as the top-most entity an Article @type with @id #article, and within that same level the “mainEntityOfPage” prop provides a value of #webpage. The difference between webpage and article types is arguably marginal (although I’d argue that the Article is the main entity of this page), but would it not be better to align these 2 signals with the same value to avoid confusing algorithms?

    • Joost de Valk

      Hey Richard,

      that schema graph actually says: “this Article (identified by #article) is the main entity of the entire page (identified by #webpage)”. So they’re separate things, albeit indeed very closely related.

      The syntax of mainEntityOfPage can be very confusing I’ve found in the last few weeks.

      • Richard Hearne
        Richard Hearne  • 8 months ago

        Hmmm… I’m not so sure Joost. “mainEntityOfPage” is used also to disambiguate when multiple entities sit at the top level (e.g. you output multiple structured data blocks in separate elements). But in your case the top-level entity is one thing (#article) but you are then saying that the mainEntityOfPage is #webpage. Structured markup like this is hard, and I’m not saying my interpretation is correct or that yours is incorrect, but I suspect that this structure may send conflicting signals to at least some consumers of this data. I hope we canhear from some of the people involved in defining these schema so that we can get some further clarification.

        As an aside, I think that the #article entity should actually be mainEntity (based on what you mention above), rather than mainEntityOfPage which often indicates that the current page is about an entity which can be best defined by another ID (very often a different URL).

        • Jono Alderson
          Jono Alderson  • 8 months ago

          That’s what we’re doing at the moment. The article is the ‘mainEntityOfPage’ of the #webpage ID.

  15. Arash Ghaemi
    Arash Ghaemi  • 8 months ago

    I’ve had the hardest time learning schema.

    Thank you so much as this will be way easier to understand and explain to clients!

    • Joost de Valk

      My pleasure Arash!

  16. Monique
    Monique  • 8 months ago

    Thanks for this update, looking forward to explore it!

    • Joost de Valk

      Have fun with it, keen to hear about your experience!

  17. Imran
    Imran  • 8 months ago

    I’m very happy with this updates, We tried some plugin for fix issues of my schema/structured data but failed. Thanks ‘Yoast SEO’ for caring us.

    • Joost de Valk

      Our pleasure Imran!

  18. Garrett Owens
    Garrett Owens  • 8 months ago

    As always I love what Yoast and does have been using Yoast for all my client’s sites. I do have one question though. I use the Genesis framework with all of my client’s websites. They also provide schema, will this overlap or interfere with that?

    • Joost de Valk

      Yes it does overlap with theirs, but luckily, Genesis legend Bill Erickson has already got you covered, check out his post on how to disable the Genesis Schema.

  19. Mehmet Ortaç
    Mehmet Ortaç  • 8 months ago

    Good news. Thank you so much for that. I could improve my blog page rich snippet.

    • Joost de Valk

      Good luck with that Mehmet :)

  20. Kingsley Felix
    Kingsley Felix  • 8 months ago

    So how does none technical webmasters like us implement it? and what happened to the built in theme version or plugin we already use?

    In our company we use theme built and plugin (the plugin made by AMPFORWP makers)

    • Joost de Valk

      If you use Yoast SEO, you don’t have to implement this, we did it for you.

  21. Zino Ostendorf
    Zino Ostendorf  • 8 months ago

    Hi, Joost. I’ve been using the Yoast SEO Pro and Yoast Local plugins together for some months now. Easy implementation of schema.org for local businesses.

    However, with this update, is there action required from the user end or are @id automatically applied?

    • Joost de Valk

      If you’re using Local and Yoast SEO Premium, all you have to do is update both and you’re good to go :)

  22. Alex Williams
    Alex Williams  • 8 months ago

    Will this improve schema for job listing. Will yoast be doing anything in the future to help those who post job listings. Seems Google hates third party job boards. Constantly getting manual actions strange thing is I do nothing then tell Google its fixed in a one liner message and bam the manual action gets lifted. I wonder if Google do this because of the schema data? I love yoast its so user friendly and a must have for any WordPress site.

    • Joost de Valk

      This won’t improve it by itself, but it does allow for us to help you with that a whole lot easier.

  23. Ronald Gijsel
    Ronald Gijsel  • 8 months ago

    I’ll link to this as I mentioned this during my WCLDN talk – as if I knew this was coming ;-) PS – will this help with voice searches or is this a different markup?

    • Joost de Valk

      Well voice searches use the same index in google as normal searches. I think this will allow Google and others to see relationships between entities better which should help in the long run :)

      • Ronald Gijsel
        Ronald Gijsel  • 8 months ago

        The reason why I asked this, is because I read that in order for a business to be ‘recognised’ by Google home and Alexa, you need to submit details to a register and get verified. It’s a bit of a vague territory between GMB, Bing Business, Schema, Alexa and local SEO, etc. I am sure this schema markup is a step in the right direction.
        Plus my money is on Yoast to make this connection (and understanding) happen soon ;-)
        btw, I appreciate the Schema is much bigger than just business listings, but I always used this to test SEO visibility.
        Great work team Yoast!

  24. support68
    support68  • 8 months ago

    Schema has never really excited you before. I have realised its importance but always found it hard going to implement. That is until now! Yoast Premium 11.0 has me very excited.
    Yet another reason to help me reinforce just how important it is that my clients use Premium rather than Yoast free version. I see another marketing opportunity right here, right now.
    Thank you Joost!

    • Joost de Valk

      My pleasure!!

  25. Almar Online
    Almar Online  • 8 months ago

    Woauw.. this is truly amazing work. And sooo cool that you are willing to share this in the open and not only keep the knowledge for yourself for the sake of commercial reasons. Let’s take structured data to a level like it really could be.

    • Joost de Valk

      Yes, let’s. We don’t believe in restricting ideas.

      • Almar Online
        Almar Online  • 8 months ago

        That’s a great attitude. What does happen with existing structured data (those loose bits & pieces where Jono talks about) generated from themes or other plugins by the way?

        • Joost de Valk

          Nothing happens to them, they stick around, they are just not connected to the main graph and it’s therefor harder to distinguish their relationship to the rest of the content.

  26. Karl
    Karl  • 8 months ago

    great stuff, does that mean I don’t have to finish my structured data course as it has been the toughest one so far. Or is that just wishful thinking

    • Joost de Valk

      Hey Karl,

      I would still suggest following it because more knowledge is always going to help you :)

      • Nikhil Sinha
        Nikhil Sinha  • 8 months ago

        This article gives the light on a very important topic and provides in-depth knowledge. I want to say thanks for this kind of articles.

  27. Ralph du Plessis
    Ralph du Plessis  • 8 months ago

    Great timing!! I’m working on a “How to do a schema audit for SEO” guide and experiencing so much frustration…. not to mention the challenges with client sites.
    Thank you!

    • Joost de Valk

      Glad you’re as excited about it as we are Ralph :)