Implementing JSON-LD for Personal Websites

Implementing JSON-LD for Personal Websites

JSON-LD (JSON Linked Data) is a standardized format for adding structured data to webpages, allowing web crawlers and AI engines to understand the semantic structure of a site. Implementing JSON-LD can lead to richer link previews, improved search rankings, and better citation accuracy by LLM crawlers.

JSON-LD Fundamentals

JSON-LD is implemented by adding a <script> tag with the MIME type application/ld+json to the <head> section of an HTML document. This ensures the browser's JavaScript engine ignores the content while specialized crawlers, such as Googlebot, parse it.

Core Components of a JSON-LD Document

  • @context: Defines the vocabulary used. Most web crawlers standardize on Schema.org.
  • @graph: A labeled, directed graph containing multiple nodes connected by arcs.
  • Nodes: Individual entities within the graph, defined by:
    • @type: The category of the node (e.g., WebSite, Person).
    • @id: A unique identifier, typically a URL with a hash (e.g., https://example.com/#website), which allows crawlers to merge properties of the same entity across different pages.
    • Properties: Key-value pairs describing the attributes of the node.

Essential Nodes for Personal Websites

To maximize SEO and discoverability, personal websites should implement a specific set of Schema.org nodes.

WebSite and WebPage

The WebSite node provides high-level metadata about the entire domain, such as the site name and description. While the root page should contain a fully detailed WebSite node, subsequent pages can use a slimmed-down version to provide sufficient context for single-page crawlers.

WebPage describes the physical HTML page and its content. It is a general node that can be further specialized into subtypes like ProfilePage (for "About" pages) or CollectionPage (for blog indexes or profile lists).

Person

The Person node is critical for content quality metrics and LLM citations. It should be included on every page of a personal site to establish a consistent identity. Key properties include:

  • url: The root page anchoring the identity.
  • name, givenName, familyName: Clear identification of the individual.
  • sameAs: A list of URLs to other professional profiles (GitHub, LinkedIn, etc.), which helps crawlers build a knowledge graph and disambiguate individuals with common names.
  • image: A canonical photo or logo associated with the person.

SoftwareApplication

For developers showcasing projects, the SoftwareApplication node (or subtypes like MobileApplication or WebApplication) provides metadata about the software. It is recommended to include an offers property with a price of 0 for free and open-source software (FOSS) to ensure complete metadata.

Organizing Content and Navigation

BreadcrumbList

BreadcrumbList allows site owners to control how search engines represent the page hierarchy in search results. This is particularly useful for shortening long URL paths into a readable format (e.g., Home > Blog > Post Title).

Blog and BlogPosting

For sites with a technical blog, a two-tier structure is used:

  1. Blog: This node is placed on the blog index page and acts as the bridge between the WebSite and individual posts. It can include a license property (e.g., Creative Commons) to inform crawlers of usage rights.
  2. BlogPosting: This node is applied to individual articles. It should include headline, datePublished, dateModified, and author (which points back to the Person node). The image property should mirror the Open Graph (OG) image used for social link previews.

Implementation Summary Table

Node Type Recommended Placement Primary Purpose
WebSite All pages (Full on root) Domain-level metadata and site naming
Person All pages Identity, authority, and LLM citation
WebPage All pages Description of the specific HTML document
BreadcrumbList All non-root pages Search engine path representation
Blog Blog index page Aggregator for blog posts
BlogPosting Individual blog posts Article-specific metadata and rich snippets

Sources