Getting to know, and adding, JSON-LD to a WordPress site

What is JSON-LD?

JSON-LD is a fairly new, yet very familiar, attempt to convert our rambling content into structured data, allowing machines to read, understand, and (ideally some day) connect our otherwise-non-structured data.

The web’s first attempt at this was Microformats, then Microdata, and not long after that RDFa. Each gained some traction, and in fact all are still used today, but none really solved the problem they were intended to solve: provide machine-readable structure to our incredibly varying content in our incredibly varying documents across the web.


JSON-LD is the next attempt, and it starts off on some pretty solid ground. First of all, it is based in JSON, which is already an incredibly familiar data format for anyone currently working in JavaScript, or anywhere near the web…

Next, it removes itself from our markup, in the sense that, while the JSON-LD is still contained within a script tag in your page, it is not intermingled with your CSS classes (as Microformats data is) or nestled inside of custom HTML attributes (as Microdata and RDFa data are).

Additionally, all of the structured data is contained within a single block of JSON, so it is easy to find and make use of, unlike Microformats, Microdata and RDFa, where the data is separated into pieces and strewn across the content for which it is meant to provide structure.

But don’t just listen to me, listen to these far-smarter people talk about why JSON-LD is a good thing:

How Can I Get Started with JSON-LD?

The JSON-LD home site offers links to videos, the W3C spec, documentation and even a playground where you can test your JSON-LD to see if it will be interpreted as you desire.

Google also provides a Structured Data Testing Tool, where you can provide a URL or paste in your code, then see how it validates.

But if you’re using a CMS (like the title of this article suggests) then you are probably looking for something automated, right? (I know I was!)

Getting JSON-LD into WordPress

writes about Implementing JSON-LD in WordPress, explaining what you want where, and providing code samples for what it should look like when you are done, even providing a small collection of functions to do it all for you! Just copy, paste, and Refresh.

Here is an example from my home page, so this is the Organization (nicely minified!):

{"@context":"http:\/\/\/","@type":"Organization","name":"Aaron T. Grogg","logo":"https:\/\/\/resume\/Atg-clean.png","url":"https:\/\/\/","sameAs":["https:\/\/\/aarontgrogg","https:\/\/\/aarontgrogg","https:\/\/\/in\/aarontgrogg","https:\/\/\/+aarongrogg\/"],"contactPoint":[{"@type":"ContactPoint","url":"https:\/\/\/","email":"[email protected]","contactType":"customer support"}]}

But if all of that copying and pasting and editing just sounds too.. exhausting… then, since we’re talking about WordPress, naturally there are already several plugins at your disposal:

  • JSON-LD for Article: After a standard installation, the plugin just worked, automatically adding the JSON-LD code to the bottom of my pages. As the name implies, the JSON-LD is added only to articles (aka Posts). Depending on your site, this may be enough. However, you might also want to add structured data to Pages (like About or Contact Us) or even your homepage (to reflect your Organization). The code is also not minified, which isn’t huge, but it is something. Also, there is no @id property for the Person data, and for my site, the image property is appearing as null; not sure how I would resolve that. Here is an example from a recent post:
        "@context": "",
        "@type": "Article",
        "headline": "Adding HTTPS to my Dreamhost WordPress site",
        "author": {
            "@type": "Person",
            "name": "Aaron T. Grogg"
        "datePublished": "2015-12-11",
        "articleSection": "hosting",
        "url": "",
        "image": null,
        "publisher": {
            "@type": "Organization",
            "name": "Aaron T. Grogg"
  • Markup (JSON-LD) structured in Standard installation, but unlike the previous plugin, where clicking Activate was all that was required, this plugin comes with a Settings page. And no instructions, other than “Open ‘ Setting’ menu” in the plugin’s Installation tab… The Settings page offers multiple Schema Types (Article, Blog Posting, Breadcrumb, Event, News Article, Organization, and Web Site), and after clicking through and activating one at a time, I only saw Organization provide something consistently useful, allowing me to provide a URL to my image and a slew of social sites, but there is still no @id property for the Person or Organization. I could not get a data structure like that above that pertained to the specific post or page that I was viewing. The code is also not minified, which isn’t huge, but it is something. Here is an example of the Organization JSON-LD:
        "@context": "",
        "@type": "Organization",
        "name": "Aaron T. Grogg",
        "url": "",
        "logo": "",
        "sameAs": [
  • Structured Data of JSON-LD: Standard installation, simple installation, no configuration required. I got data structures on the home page, Posts, and Pages, all at the bottom of the page, and all were minified! There is still no @id property for the Person data (am I understanding that property wrong?), and the plugin seems to be providing its own image value if it can’t find one. Also, on Posts and Pages, it duplicates the entire content into the articleBody property (as it is supposed to do, I guess…), which could create a good bit of bloat, but again, I think that is the correct behavior for the data structure, so I’m not sure what you can do about that… Here is an example of the Organization JSON-LD:
    {"@context":"http:\/\/","@type":"WebSite","url":"https:\/\/","potentialAction":{"@type":"SearchAction","target":"https:\/\/\/?s={search_term}","query-input":"required name=search_term"}}


Although it required me to manually add and edit files on my server, I am able, and I also like having direct control over my code, so I went with Richard Baxter’s version (with a few edits, naturally…). His code is clean and simple, and since it is not someone else’s plugin, I don’t have to worry about my changes getting overwritten. Of course, this does mean that I have to watch the spec and maintain my code, so, that’s a small negative.

If, however, you are not able to gain access to the site’s server, then I would very comfortably recommend the Structured Data of JSON-LD plugin. The JSON-LD looked fine, was nicely minified, I liked that it was at the bottom of my pages, and that it worked on posts, pages, and my home page, knowing what data to structure to use in each case.

What is the Future for JSON-LD?

If you took the time to read any of the other articles referenced above, you likely gathered that there really isn’t much practical use for JSON-LD (or any other structured data format, for that matter) right now.

Someday this may help your site’s SEO, and might even allow you or someone else to create data crawlers that can find and connect data across the web. But like a lot of other tech possibilities, if ti doesn’t cost you much to do it, then you will already have it in place if/when that day arrives, and your site will be ready to go!

Here are two articles that talk about how JSON-LD could positively affect your SEO rankings and click rates:

Until then, happy structuring,

10 Responses to Getting to know, and adding, JSON-LD to a WordPress site

  1. nicole says:

    So, I tried the plugin you recommended and it just…didn’t do anything. What step am I supposed to take after install?

    I can access my servers but I’m honestly just not understanding the other guy’s explanation.

  2. Marco says:

    Hi Aaron, nice post!

    Are you up to date with the various JSON-LD plugins for WP?

    There are 3 or 4 going around but I don’t know how to orient myself.

    Actually considering if it’s maybe worth copying and pasting the code into the html of each page/post in case of small websites made of few pages.

    What is your personal suggestion?

    Thanks a lot!

    • Hey Marco, thanks!

      My suggestion is usually “whatever works best for you”… :-)

      If the site is only a few pages, maybe manually adding does make sense, but it also means making content changes twice if that happens…

      I have not been paying attention to plugins lately, any specific ines you are considering?

  3. Marco says:

    Hey Aaron,

    consider I am a total newbie in rich snippets/schema/json-ld.

    Basically, my website is tipically a few pages (3-4-5…) and a blog section with the articles. It belongs to an organization/local business (to use schema’s dictionary): a gymnastics team/center.

    Supposedly analog to pretty much any local store or similar.

    All I know about rich snippets is from my Google customer-side experience: noticing some serps with starts, authorship, photo/video thumbnail.

    I guess those would be a big boost for a local business if they were showed in its Google records when searching stuff like “gymnastics school” in your area.

    Now that I am reading a few things about schema’s syntax, I am starting to think that maybe I could rely on a simple plugin like the one you suggest for the article section, and maybe manually edit and paste the scripts for Organization/Local Business/Product according to the page content for the 3-4-5 pages outside the blogging area of the website.

    Please correct me if my thoughts are wrong. It looks like this discipline of rich snippets is not really widespread in the “low-end/homemade” webdesigning, thus there’s not many resources around and most complete plugins are not free.

    Thanks a lot for your help!

    • Hey, Marco.

      As with most things in life, the decision really needs to be yours… :-/

      This tech is certainly not widespread, and not something tried-and-true, like say alt attributes on an img element or something, but in my book I say “what have I got to lose?”.

      If I can implement something that might make my site easier to parse for someone (or somebot), then why not? I tend to use this baseline for lots of things in webtech.

      If you wanna handcraft individual statements per page, go for it; if you wanna try a plugin or three, go for it; if you wanna close this window and forget you ever tripped on it, go for it. :-)

      The web is yours, find what makes you feel right and rock on.


      • Thanks Aaron, was just trying to get some help from your blog since I haven’t found any guideline on how to manage with rich snippets and such.

        Plus, there used to be a structured data testing tool that was supposed to give you a preview of what Google would display according to the schema/json-ld information that you put in, but it looks like it’s not giving the rich snippet preview any more.

        Thus, it gets really hard to understand what works for you if you can’t really test it

        • Understood, Marco, it is rough to get going the first time, but just so you know, I am still running tests on semantic markup I add to brand new pages myself! :-)

          To that end, Google does still have a testing tool:

          Works quite nicely!

          And, to get ready for the testing tool, here are a few other resources you might find useful (I find myself going back to them regularly):

          1. Series of Google articles about Structured Data Types. Of course it delves into AMP quite a bit, but the pieces about the actual markup, including examples, are quite useful.
          2. Once you have a good grasp of the data types, here is another series of Google articles on the actual Structured Data (find the highlighted article in the left-nav and continue reading down from there). This article also has some really good examples.
          3. And finally, the mother of all semantic markup sites (but you really need the above “understanding” first), is, which lists all of the current standards, options, many examples, and should help you get exactly the right pieces into the above examples. It is pretty dry, which is why the above articles give you a nice set-up, but when the examples above do not quite fit your needs, you will find this resource invaluable!

          Again, happy to help, and hope these resources do!

          Feel free to reach out if you hit another snag, though!


  4. Ash says:

    Hi, I’m confused as to where is the best place to add json-ld in WordPress. Would I have to insert it in multiple places? For example, should I insert json-ld in the WordPress page editor for my content on my about page instead of header or footer?

    Basically, what I’m trying to say is:

    What type of schema markup is best in the header?

    What schema markup is best for adding to a word press page like in my about page?

    What kind of schema markup goes in the footer?

    Is it a bad idea to add schema markup directly inside a wordpress page editor? If you have any videos or documentation, it would be very appreciated. Thanks!

    • Hello, Ash.

      The first thing I would recommend is checking the page source of your site, because the JSON/LD should already be in there; it was added to WP Core some time ago…

      But to answer your questions, I do not have any videos, but I would be surprised if there aren’t some out there.

      As for adding schema markup inside the WP editor, you might find that you em>can’t add the script there (WP natively blocks <script> tags in the editor), but if you can, and that works best for you, go for it!

      My only concern for this method would be having to make edits twice; I am a big fan of the DRY approach. And, once you enter your content into the editor, it is in your database, so why not let the framework build that schema block for you?

      As for the placement of the schema markup (in the header, content, or footer), it doesn’t matter. Since it is only for bots, they will find it wherever you decide to put it.

      I hope this clears things up a little,

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.