Adding JSON-LD to a Personal Website

January 05, 2017 4 mins read
Engineering

Adding JSON-LD to a Personal Website

Structured data is a standard to help search engines understand the semantic content of a website. Structured data defines a vocabulary telling search engines what the content of your website is about and providing them with additional data in a structured manner to reduce the assumptions made about the content. This blog posts shows you how you can add JSON-LD schema specifications to the different parts of your website.

What is JSON-LD?

JSON-LD is a data linking format using the JavaScript object notation (JSON) to express linked data with appropriate attributes. It is able to express the vocabulary of schema.org, a set of vocabularies to express the semantics of content, which is a joint effort of Google, Microsoft, Yahoo, Yandex and a community.

Besides JSON-LD, there are other markup notations to express the schema.org vocabulary, such as RDFa or Microdata. RDFa and Microdata attach specific tags to the HTML source defining their semantics. The schema.org vocabulary also supports hierarchical relationships of elements, which can become very messy when altering the HTML code (and it’s implicit hierarchy). In contrast, JSON-LD adds a <script /> tag to the website containing all relevant data.

As JSON-LD is straightforward to add to an existing site, I chose to mark up my website with the JSON-LD syntax using the schema.org vocabulary.

Testing JSON-LD

Writing JSON-LD is usually straightforward, but ensuring the used properties and values are correct according to the schema.org vocabulary is not easy. The Structured Data Testing Tool made by Google has been written specifically for this task. The tool also provides a validation of the specified data to comply with the requirements for leveraging Google’s rich snippet features.

The JSON-LD playground is a web application that allows you to enter JSON-LD content and analyze it. The playground is also capable of transforming the input to different output formats.

Blog posts in JSON-LD

A website containing a single blog post can be annotated with a schema similar to the following. In fact, the shown example is the schema markup for this blog post.

{
    "@context": "http://schema.org",
    "@type": "BlogPosting",
    "headline": "Adding JSON-LD to a Personal Website",
    "keywords": "",
    "url": "http://www.fabian-keller.de/blog/adding-json-ld-to-a-personal-website",
    "datePublished": "2017-01-05T00:00:00+00:00",
    "dateCreated": "2017-01-05T00:00:00+00:00",
    "dateModified": "2017-01-05T00:00:00+00:00",
    "articleBody": "...",
    "image": {
        "@type": "ImageObject",
        "url": "https://www.fabian-keller.de/thumbs/blog/adding-json-ld-to-a-personal-website/adding-json-ld-to-a-personal-website-750x400.jpg",
        "height": 400,
        "width": 750
    },
    "author": {
        "@type": "Person",
        "name": "Fabian Keller",
        "url": "http://www.fabian-keller.de"
    },
    "publisher": {
        "@type": "Person",
        "name": "Fabian Keller",
        "url": "http://www.fabian-keller.de"
    }
}

Blog overview in JSON-LD

Most blogs feature a page showing a collection of blog posts, sometimes containing the full blog post and sometimes only a short summary of the blog post. The JSON-LD annotation for a page showing a collection of blog posts is similar to:

   {
    "@context": "http://schema.org",
    "@type": "Blog",
    "author": {
        "@type": "Person",
        "name": "Fabian Keller",
        "url": "http://www.fabian-keller.de"
    },
    "blogPost": [
        {
            "@type": "BlogPosting",
            // ...
        },
        // ...
    ]
}

The blogPost attribute contains a list of all blog posts on the page. Each blog post in the collection is of the BlogPosting type that is described in the previous section. However, each blog post in the collection only contains the most important attributes and omits large attributes (such as articleBody) that are provided on the page dedicated to the blog post.

About page in JSON-LD

Everyone has an about page. Add some of your personal information with JSON-LD to help search engines identify who you are.

{
    "@context": "http://schema.org",
    "@type": "Person",
    "name": "Fabian Keller",
    "url": "http://www.fabian-keller.de",
    "jobTitle": "Software Engineer",
    "alumniOf": "University of Stuttgart",
    "gender": "male",
    "image": "http://www.fabian-keller.de/assets/images/fabiankeller_sq_sm.jpg",
    "sameAs": [
        "https://de.linkedin.com/in/fabian-keller",
        "http://stackoverflow.com/users/1262901/fakeller",
        // ...
    ]
}

By the way, the sameAs collection is a list of links to all your online profiles.

A Project page in JSON-LD

Typically, a personal website features a collection of creative work of the owner. The schema.org classification features a lot of different creative works to precisely annotate the project’s site. The following list is just an excerpt of the one’s most commonly found on personal websites:

In my case, I have some programming projects which are annotated using SoftwareSourceCode as follows:

{
    "@context": "http://schema.org",
    "@type": "SoftwareSourceCode",
    "name": "archinspec",
    "keywords": "personal,opensource",
    "url": "http://www.fabian-keller.de/code/archinspec",
    "datePublished": "2015-06-01",
    "dateCreated": "2015-06-01",
    "creator": {
        "@type": "Person",
        "name": "Fabian Keller",
        "url": "http://www.fabian-keller.de"
    },
    "image": {
        "@type": "ImageObject",
        "url": "http://www.fabian-keller.de/thumbs/code/archinspec/archinspec-750x400.jpg",
        "height": 400,
        "width": 750
    },
    "description": "<p>archinspec is a tool to ...</p>"
}

Conclusion

JSON-LD is easy to add and helps non-human visitors of your website to understand your content. The annotations are used to create rich snippets, which are becoming increasingly popular, especially on mobile devices with applications such as Google Now. Hence, JSON-LD opens your content to be featured in rich snippets and allows it to be viewed by a broader audience.

Comments

👋 I'd love to hear your opinion and experiences. Share your thoughts with a comment below!

comments powered by Disqus