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.

Why JSON-LD?

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:\/\/schema.org\/","@type":"Organization","name":"Aaron T. Grogg","logo":"https:\/\/aarontgrogg.com\/resume\/Atg-clean.png","url":"https:\/\/aarontgrogg.com\/","sameAs":["https:\/\/twitter.com\/aarontgrogg","https:\/\/www.facebook.com\/aarontgrogg","https:\/\/www.linkedin.com\/in\/aarontgrogg","https:\/\/plus.google.com\/+aarongrogg\/"],"contactPoint":[{"@type":"ContactPoint","url":"https:\/\/aarontgrogg.com\/","email":"aarontgrogg@gmail.com","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": "http://schema.org",
        "@type": "Article",
        "headline": "Adding HTTPS to my Dreamhost WordPress site",
        "author": {
            "@type": "Person",
            "name": "Aaron T. Grogg"
        },
        "datePublished": "2015-12-11",
        "articleSection": "hosting",
        "url": "https://aarontgrogg.com/blog/2015/12/11/adding-https-to-my-dreamhost-wordpress-site/",
        "image": null,
        "publisher": {
            "@type": "Organization",
            "name": "Aaron T. Grogg"
        }
    }
    
  • Markup (JSON-LD) structured in schema.org: 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 ‘Schema.org 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": "http://schema.org",
        "@type": "Organization",
        "name": "Aaron T. Grogg",
        "url": "https://aarontgrogg.com",
        "logo": "https://aarontgrogg.com/resume/Atg-clean.png",
        "sameAs": [
            "https://twitter.com/aarontgrogg"
        ]
    }
    
  • 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:\/\/schema.org","@type":"WebSite","url":"https:\/\/aarontgrogg.com","potentialAction":{"@type":"SearchAction","target":"https:\/\/aarontgrogg.com\/?s={search_term}","query-input":"required name=search_term"}}
    

Recommendation

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,
Atg

2 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.

Leave a Reply

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