JSON-LD Explained for Personal Websites

Learn how to implement JSON-LD structured data on your personal website to improve SEO, enhance search appearance, and establish your digital identity for search engines and AI crawlers.

JSON-LD, also known as JSON Linked Data, is a format for adding structured data to webpages. It can aid web crawlers in understanding the semantic structure of your site, qualifying you for richer link previews, and even potentially improving your search ranking.

It’s been 4 months since my first post where I described building this site, and Wakatime estimates I’ve spent ~100 hours coding now, not including time spent researching and testing. Since then, this site has been receiving plenty of polish, including the addition of JSON-LD on each page.

JSON-LD Fundamentals

To add JSON-LD to a page, add the following somewhere in your <head>

section:

<script type="application/ld+json">
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "WebSite",
"@id": "https://hawksley.dev/#website",
"url": "https://hawksley.dev/",
"name": "Ethan Hawksley"
},
// Insert more nodes here.
]
}
</script>

Let’s break down what each part does.

<script type="application/ld+json">

This declares a new script with MIME type application/ld+json

. Since it has this type specified, the browser’s JS engine won’t run it. Specialised crawlers like Googlebot look out for these elements and parse the contents.

{
"@context": "https://schema.org"
}

Here, a JSON object is initialised and the property @context

is set to https://schema.org

. In JSON-LD, the structure of data is determined by assigning the appropriate context. Web crawlers are standardised on Schema.org,, opens in new tab which defines all the valid key-value pairs for the JSON.

Now that we’ve defined the schema our JSON-LD is following, we can describe our webpage!

{
"@graph": [
{
"@type": "WebSite",
"@id": "https://hawksley.dev/#website",
"url": "https://hawksley.dev/",
"name": "Ethan Hawksley"
}
// Insert more nodes here.
]
}

A JSON-LD document can be thought of as a labelled, directed graph, stored under @graph

. The graph contains multiple nodes, connected to each other with directed arcs.

Nodes have:

@type

Describes what the node is, e.g.WebSite

orSoftwareApplication

@id

A unique identifier for the node, typically a URL with a unique hash value at the end- Properties - Key/Value pairs that describe the attributes of the node

In the example above, the type is WebSite

, the ID is https://hawksley.dev/#website

, and it has two properties, url

and name

Web crawlers can merge the properties of a node across multiple pages, as long as they share an ID. However, scrapers that only read one page - such as LLMs - will not merge the properties. When JSON-LD is reused across pages, striking this balance is important to keep in mind. It is best practice for the ID to be a URL followed by a hash, such as #website

, that uniquely identifies the node.

Although the Schema.org context defines many types of nodes, this guide will only be covering nodes that have noticeable SEO impact. If you’re interested in more, look up the semantic web - it’s a fun rabbit hole.

Let’s move on to which nodes each page on our site should include. For each type, I’ve included the JSON-LD from this site, so you can copy-paste and edit it to fit your own.

WebSite

You’ve seen an extract of WebSite

earlier! Now here’s the full version:

{
"@type": "WebSite",
"@id": "https://hawksley.dev/#website",
"url": "https://hawksley.dev/",
"name": "Ethan Hawksley",
"alternateName": ["hawksley.dev", "Hawksley"],
"description": "The personal site and technical blog of Ethan Hawksley, a UK-based CS student with a focus on systems programming, low-level computing, and cybersecurity.",
"inLanguage": "en-GB",
"publisher": {
"@id": "https://hawksley.dev/#person"
},
"image": {
"@type": "ImageObject",
"@id": "https://hawksley.dev/#website-image",
"url": "https://hawksley.dev/logo-square.png",
"caption": "Ethan Hawksley Logo"
}
}

WebSite

explains the metadata about the site. It gives crawlers hints on how to display your site.

Here, you can see that Google has interpreted the name field as representative of the domain and is labelling the result appropriately.

Although WebSite

applies to every page, you don’t need to include the full version of it on every page. The root page of the domain should be fully detailed, but it is perfectly acceptable for other pages to have a slimmed-down version:

{
"@type": "WebSite",
"@id": "https://hawksley.dev/#website",
"url": "https://hawksley.dev/",
"name": "Ethan Hawksley"
}

This gives sufficient context to single-page crawlers so they correctly name the site, but they don’t need the full details.

WebPage

WebPage

describes the current page, but it’s important to distinguish it from other types like BlogPosting

(covered later). WebPage

represents the physical page itself, the HTML. It contains the content of the page.

{
"@type": "WebPage",
"@id": "https://hawksley.dev/blog/hack-club-campfire/#webpage",
"url": "https://hawksley.dev/blog/hack-club-campfire/",
"isPartOf": {
"@id": "https://hawksley.dev/#website"
},
"name": "Winning the Hack Club Campfire Hackathon",
"inLanguage": "en-GB",
"breadcrumb": {
"@id": "https://hawksley.dev/blog/hack-club-campfire/#breadcrumb"
}
}

There are more specific subtypes of WebPage

. In this post, I’ll cover ProfilePage

and CollectionPage

. You can find less common ones at the bottom of Schema.org’s definition for WebPage., opens in new tab

Person

Another node that every page on a personal website should have is Person

. It describes who you are, which Google uses as part of their content quality metric. Increasingly, LLM crawlers are also using it to decide who to cite in their answers.

Unlike WebSite

, it is important enough context that you should include it on all of your site’s pages.

Warning - Quite Long!

{
"@type": "Person",
"@id": "https://hawksley.dev/#person",
"url": "https://hawksley.dev/",
"name": "Ethan Hawksley",
"alternateName": "ethanhawksley",
"givenName": "Ethan",
"familyName": "Hawksley",
"description": "Long Description",
"disambiguatingDescription": "Shorter Description",
"jobTitle": "Computer Science Student",
"knowsLanguage": "en-GB",
"knowsAbout": [
// Keywords
],
"nationality": {
"@type": "Country",
"name": "United Kingdom"
},
"homeLocation": {
"@type": "Place",
"address": {
"@type": "PostalAddress",
"addressCountry": "GB"
}
},
"affiliation": {
"@type": "HighSchool",
"url": "https://www.alcestergs.co.uk",
"name": "Alcester Grammar School",
"sameAs": [
"https://www.wikidata.org/wiki/Q4713005",
"https://en.wikipedia.org/wiki/Alcester_Grammar_School"
]
},
"alumniOf": [
{
"@type": "HighSchool",
"url": "https://www.brookeweston.org",
"name": "Brooke Weston Academy",
"sameAs": [
"https://www.wikidata.org/wiki/Q4974495",
"https://en.wikipedia.org/wiki/Brooke_Weston_Academy"
]
}
],
"image": {
"@type": "ImageObject",
"@id": "https://hawksley.dev/#person-image",
"url": "https://hawksley.dev/ethan-hawksley.png",
"caption": "Ethan Hawksley",
"width": 1200,
"height": 1200
},
"sameAs": [
"https://github.com/ethan-hawksley",
"https://www.linkedin.com/in/ethanhawksley",
"https://lobste.rs/~ethanhawksley",
"https://news.ycombinator.com/user?id=ethanhawksley"
// etc. etc.
]
}

Phew! There’s plenty of properties for Person

. I find that it helps to be more descriptive, rather than less, when it comes to filling it out. Let’s look at the most important properties:

url

Points to your root page, anchoring the node.name

,givenName

,familyName

Clearly describes your name.image
Preferably a photo of you, or a logo you are affiliated with. Connects you to a canonical image of you.sameAs
Immensely useful for disambiguation, especially if you have a common name. It cleanly informs crawlers what your other profiles are, letting them build a knowledge graph representation of you across multiple pages. At the time of writing, /g/11m62cgdtf, opens in new tab is my Google knowledge graph ID.

Source: Hacker News