JSON-LD Explained for Personal Websites | Ethan Hawksley Skip to content<br>← Back to blog<br>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.<br>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.<br>JSON-LD Fundamentals<br>To add JSON-LD to a page, add the following somewhere in your section:<br>"application/ld+json"><br>"@context": "https://schema.org",<br>"@graph": [<br>"@type": "WebSite",<br>"@id": "https://hawksley.dev/#website",<br>"url": "https://hawksley.dev/",<br>"name": "Ethan Hawksley"<br>},<br>// Insert more nodes here.<br>Let’s break down what each part does.<br>"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.<br>"@context": "https://schema.org"<br>}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.<br>Now that we’ve defined the schema our JSON-LD is following, we can describe our webpage!<br>"@graph": [<br>"@type": "WebSite",<br>"@id": "https://hawksley.dev/#website",<br>"url": "https://hawksley.dev/",<br>"name": "Ethan Hawksley"<br>// Insert more nodes here.<br>}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.<br>Nodes have:<br>@type - Describes what the node is, e.g. WebSite or SoftwareApplication<br>@id - A unique identifier for the node, typically a URL with a unique hash value at the end<br>Properties - Key/Value pairs that describe the attributes of the node<br>In the example above, the type is WebSite, the ID is https://hawksley.dev/#website, and it has two properties, url and name.<br>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.<br>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.<br>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.<br>WebSite<br>You’ve seen an extract of WebSite earlier! Now here’s the full version:<br>"@type": "WebSite",<br>"@id": "https://hawksley.dev/#website",<br>"url": "https://hawksley.dev/",<br>"name": "Ethan Hawksley",<br>"alternateName": ["hawksley.dev", "Hawksley"],<br>"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.",<br>"inLanguage": "en-GB",<br>"publisher": {<br>"@id": "https://hawksley.dev/#person"<br>},<br>"image": {<br>"@type": "ImageObject",<br>"@id": "https://hawksley.dev/#website-image",<br>"url": "https://hawksley.dev/logo-square.png",<br>"caption": "Ethan Hawksley Logo"<br>}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.<br>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:<br>"@type": "WebSite",<br>"@id": "https://hawksley.dev/#website",<br>"url": "https://hawksley.dev/",<br>"name": "Ethan Hawksley"<br>}This gives sufficient context to single-page crawlers so they correctly name the site, but they don’t need the full details.<br>WebPage<br>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.<br>"@type": "WebPage",<br>"@id": "https://hawksley.dev/blog/hack-club-campfire/#webpage",<br>"url": "https://hawksley.dev/blog/hack-club-campfire/",<br>"isPartOf": {<br>"@id": "https://hawksley.dev/#website"<br>},<br>"name": "Winning the Hack Club Campfire Hackathon",<br>"inLanguage":...