Implementing JSON-LD for Personal Websites

JSON-LD (JSON for Linked Data) is a standardized format for adding structured data to webpages. By providing a machine-readable map of a site's content, JSON-LD helps web crawlers and LLMs understand the semantic structure of a website, which can lead to richer link previews, improved search rankings, and more accurate citations in AI-generated answers.

Core Fundamentals of JSON-LD

To implement JSON-LD, developers add a <script type="application/ld+json"> block within the HTML <head> section. Because of the specific MIME type, the browser's JavaScript engine does not execute the code; instead, it is parsed by specialized crawlers like Googlebot.

The Schema.org Context

Most web crawlers standardize on Schema.org, a collaborative project that defines the valid key-value pairs for structured data. By setting the @context property to https://schema.org, the JSON object tells the crawler which vocabulary is being used to describe the page.

The Graph Structure

JSON-LD documents are structured as labeled, directed graphs stored under the @graph key. Each node in the graph contains:

  • @type: Defines the nature of the node (e.g., WebSite, Person, SoftwareApplication).
  • @id: A unique identifier, typically a URL followed by a hash (e.g., https://example.com/#person), which allows crawlers to merge properties of a node across multiple pages.
  • Properties: Key-value pairs describing the attributes of the node.

Essential Nodes for Personal Websites

For a personal website, several specific nodes provide the most significant SEO and discoverability impact.

WebSite and WebPage

WebSite provides high-level metadata about the entire domain, such as the site name and description. While the full WebSite node should be on the root page, slimmed-down versions can be used on subpages to provide context for single-page crawlers.

WebPage describes the physical HTML page. It is distinct from content-specific types like BlogPosting. Subtypes include ProfilePage (used for "About" pages) and CollectionPage (used for lists of posts or profiles).

Person

The Person node is critical for personal sites as it informs Google's content quality metrics and helps LLM crawlers decide who to cite. Key properties include:

  • url: The root page of the site.
  • name: The full name of the individual.
  • sameAs: A list of URLs to other profiles (GitHub, LinkedIn, etc.), which is essential for disambiguation and building a knowledge graph.
  • image: A canonical image of the person.

SoftwareApplication

When showcasing projects, the SoftwareApplication node provides metadata about the software. It should include the applicationCategory (referencing Google's definitions) and an offers object. Even for free and open-source software (FOSS), the price should be explicitly set to 0 to ensure the node is valid.

BreadcrumbList

BreadcrumbList describes the hierarchical path of a page. This allows search engines to display a shortened, readable path (e.g., Home > Blog > Post) in search results rather than a raw URL, which is particularly useful for sites with deep directory structures.

Blog and BlogPosting

For sites with a technical blog, the Blog node should be placed on the index page to link the WebSite to individual posts. Each individual post should use a BlogPosting node, which includes the headline, datePublished, dateModified, and author (which should point to the Person node).

Implementation Considerations and Trade-offs

While JSON-LD provides clear benefits for machine readability, it introduces several technical and philosophical trade-offs.

Consistency and Maintenance

Maintaining JSON-LD requires duplicating information already present in the HTML. This can lead to consistency issues if the metadata is not synced with the page content. As one user noted, Google may ignore schema if the JSON-LD text does not match the visible page content.

JSON-LD vs. Other Structured Data

JSON-LD is one of several ways to implement structured data using the Schema.org vocabulary. Alternatives include RDFa and Microdata, which allow developers to embed metadata directly into HTML tags rather than using a separate script block. However, JSON-LD is widely preferred due to its ease of implementation and the simplicity of its separate JSON block.

The Impact of LLMs and Zero-Click Searches

There is ongoing debate regarding the utility of JSON-LD in the modern search landscape. Some contributors argue that structured data now primarily benefits the search engine by enabling "zero-click" results—where the LLM provides the answer directly on the search page, preventing the user from ever visiting the site.

"Google has nowadays switched to giving people lengthy LLM-generated versions of my stuff, with errors, above pointing people to my actual stuff."

Despite this, others argue that providing structured data remains the most pragmatic way to ensure a search engine's interpretation of your identity and content is accurate, even if the traffic patterns are shifting.

Sources