An Overview of JSON-LD

Subtitle: Improving your SEO indexing

Note: Graphics & layout will be morphing over the next month.


Before starting, I would like to present an instance of hyperbole with a comical twist:

“In the evolving world of digital connectivity, data has become more valuable than a gram of antimatter!”[anonymously submitted from the state-run ‘Asylum for Burned-Out Marketers’]…lol…ahem…

…now that the mood has been set…


Hi! My name is derek, your narrator (…just pretend you hear me!), and this article is an overview of the structured data exchange format called JavaScript Object Notation-Linked Data (JSON-LD). My intent is to give you, the reader, an understanding of the JavaScript/JSON/JSON-LD relationship and how JSON-LD has become the preferred structured data exchange format today. To help solidify these ideas, I have delineated a practical JSON-LD example for improving your post’s search engine indexing using the content management software (CMS), WordPress (WP). Finally, I will share my concluding thoughts. Several resource links are included for those of you wanting to further explore JSON-LD and the technologies it comprises.

JavaScript/JSON/JSON-LD Relationship:

The relationship with the established technologies that comprise the JSON-LD format has helped JSON-LD become widely accepted. JavaScript has been around since Brendan Eich created it in 1995. Douglas Crockford specified the JSON format and made it popular beginning in the early 2000s. Schema.org was founded in 2011 giving us serialized Resource Definition Frameworks (RDFs) in the forms of the supported Microdata, RDFa, as well as JSON-LD, schemas. Taken collectively, we have the technological components to create general equations showing these relationships. These equations are:

Equation 1: JSON-LD = JSON + RDF

Equation 2: JavaScript object literal syntax = JSON syntax (albeit, with a couple of minor modifications)

Basically, you can say that JSON-LD is JSON using a modified JavaScript object literal syntax wrapped in an RDF from schema.org which was founded by Google, Microsoft, Yahoo and Yandex in 2011.

Preferred structured data exchange format today:

The widespread deployment of JSON-LD as a structured data exchange format is certainly a testament to its popularity! The major search engine companies prefer its usage for SEO indexing. The web development community has embraced its simplistic elegance as a lightweight, easy-to-understand format capable of identifying or tagging practically anything. And, it can be injected into your HTML! For WordPress, one method which I am using for this article involves utilizing a snippet of PHP.

Practical Application:

The following is an example of a JSON-LD application that will improve your post’s SEO indexing. It works by inserting JSON-LD between an HTML tag set from the WordPress header.php file. Since we will be using PHP (yes, you are intermediate readers but…), I am issuing the following caveats before proceeding any further (then I am able to say ‘I told you so!’…lol!!!):

  • Configure the PHP code in the website’s backend. Not in the theme editor from the WordPress GUI! Why? If something happens and your website becomes dysfunctional, you may lose the theme editor feature and it would be best to be in the backend directory at this point.
  • If you want your custom code changes to become permanent, then you have to create a child theme.
  • Be observant of all changes you make and leave comments with your custom code for future clarification.

To insert JSON-LD into an HTML document, you need to place JSON-LD in a new custom field from the posting page you want your search engine indexing improved. But first, let’s generate our JSON-LD!

You will quickly find that there is no shortage of online JSON-LD generators. The problem is finding the one that best suits your requirement. Or, you can simply write the notation yourself but are you gaining anything? For me, it’s the time factor! You can decide for yourself. I am going to use one of the Merkle SEO Tools called ‘Schema Generator’. For my JSON-LD data, I will use this article which is being ‘typeset (lol)’ in the Gutenberg block editor. You may need to enable ‘Custom fields’ in this editor’s Preferences/Panels menu (upper right – 3 vertical dots icon) if you do not see a title called ‘Add New Custom Field’ towards the bottom area of your post page.

Fig. 1: Custom field section

Now this Merkle JSON-LD generator is very easy to use. Simply plug in the appropriate article data starting with the markup you want to create. In this example, I am creating a schema markup for my article. From there, you choose your ‘type’ and so on. After you have finished, copy it (click the blue icon button). Important: observe that your JSON-LD wraps the schema in a script tag set with the MIME type ‘Application/ld+json.’ I find this noteworthy as it shows how the different technologies coalesce. Now, we can proceed to create our custom field.

Fig. 2: Merkle Schema Generator for JSON-LD
Fig. 3: Generated JSON-LD. Image from Visual Studio Code

Back in the Gutenberg editor, I scroll down to where it says ‘Add New Custom Field.’ Under the ‘Name’ title, I click ‘Enter new’ and give the schema an appropriate name. For my purpose, I have an article on the subject of JSON-LD. And, I want the name to specifically identify itself as a schema.  Therefore, a suitable name for my article would be something like ‘article_json-ld_schema.’ This is the name I am going to use. You can create your own. After typing in my custom field name, I copy the JSON-LD from the Merkle schema markup generator and paste it into the ‘Value’ field which is to the right of the ‘Name’ field (reference Fig. 4). Once copied, I click on the ‘Add Custom Field.’ After the editor updates, you will see your new custom field above the ‘Add New Custom Field’ title. We are now ready to inject JSON-LD within an HTML tag set.

Fig. 4: Seen before clicking ‘Add Custom Field’
Fig. 5: Seen after clicking ‘Add Custom Field’

To insert my article’s JSON-LD, I am going to use the following generic PHP code snippet. It is:

<?php
$schema = get_post_meta(get_the_ID(), ‘schema’, true);
if(!empty($schema)) {
echo $schema;
}
?>

Note: I can not ascribe any attribution to the above as I have forgotten when & where I first saw this piece of code.

Looking at the code, you see it uses a post’s ID number for identification and does a boolean check on ‘schema’ which is a placeholder for the name, in our case, of a custom field. If the condition is true, then the ‘Value’ for the custom field ‘schema’ is inserted within the HTML head section where search engines will parse it thereby improving your SEO indexing. Of course, this ‘Value’ is the JSON-LD that you copied earlier. My code looks like this:

<?php
$schema = get_post_meta(get_the_ID(), ‘article_json-ld_schema’, true);
if(!empty($schema)) {
echo $schema;
}
?>

You can continue to add schema by reiterating the code (minus the PHP tags) with new custom field names and remaining within the PHP tags themselves. For example:

<?php
	$schema = get_post_meta(get_the_ID(), 'post_pov1_schema', true);
	if(!empty($schema)) {
    	echo $schema;
	}
	                                  .
                                          .
                                   ...more code...
                                          .
                                          .

	$schema = get_post_meta(get_the_ID(), 'article_json-ld_schema', true);
	if(!empty($schema)) {
    	echo $schema;
	}
	?>

And remember: your code has your custom field name in the ‘schema’ placeholder.

Next, I proceed to my website’s backend. I am hosted on GreenGeeks so I will be using the web hosting control panel software called cPanel. From the cPanel graphical user interface (GUI), I will go to my directory and open the header.php file (in edit mode) which is within my child-theme folder. And, just before the </head> tag in this file, I will insert my PHP with comments. I then update the file. Finally (optional but recommended), I check my post page for any errors by opening it with several different browsers. This will test for any errors against the major browser engines. These are the Blink, Gecko and WebKit browser engines.[Trivia alert: I did not know until I researched this article that Apple’s WebKit is a fork of the KHTML engine used by KDE which happens to be a Linux distro I am familiar with. Wow! Learn something new every day, eh!]

Note: You can view your post’s page source and see the injected JSON-LD by pressing the following relevant shortcut and scrolling down to the MIME type I pointed out earlier:

  • Google Chrome, Microsoft Edge, Mozilla Firefox: ‘Ctrl + U’
  • Safari: ‘Option + Command + U’

Concluding remarks:

I am hoping I was able to achieve my article’s intent with you, the reader! I am also hoping that, perhaps, I have, in some small way, fanned a greater ‘fire’ within you for the fascinating world of web technology. JSON-LD is but a very, very, small view of the panoramic magic that can be conjured by web technology today! You will never be disappointed…perhaps exasperated at times…lol!

Signature image for Derek Lloyd

Resource links: