Skip to content
bhavvesh.in
3 min readUpdated

How JSON-LD, Person schema and sameAs links help search engines connect your name, your domain and your work into one knowledge graph.

The short answerA developer portfolio needs Person, WebSite and BreadcrumbList schema, plus Article markup on writing. Define the Person once and reference it by @id everywhere else, list in sameAs only profiles that link back to you, mark up only what visitors can see, and validate with Google's Rich Results Test and the Schema Markup Validator.

Key takeaways

  • A developer portfolio needs three schemas — Person, WebSite and BreadcrumbList — plus Article markup on writing and a CreativeWork subtype on project pages.
  • Define the Person once and reference it by @id everywhere else, because two definitions of the same @id on one page contradict each other.
  • List in sameAs only profiles that link back to you, and remove dead, redirecting or login-walled URLs.
  • Mark up only what visitors can see, and validate with both Google's Rich Results Test and the Schema Markup Validator.

When someone searches your name, Google is trying to answer a question: is this a person it knows about? Structured data is how you introduce yourself formally. A Person schema with consistent sameAs links across GitHub, LinkedIn and your domain gives the crawler an unambiguous identity to build on.

The three schemas that matter

For a portfolio, you need exactly three: Person (who you are, what you do, where else you exist), WebSite (what this domain is and who owns it), and BreadcrumbList (how pages relate). Project pages benefit from CreativeWork markup, or one of its subtypes such as SoftwareSourceCode, which adds a repository and a programming language; articles from Article markup with author linking back to your Person entity via @id.

The @id linking is the part most people miss. Every schema on every page should reference the same canonical Person node. That repetition is what turns scattered mentions into a knowledge panel.

Write it once, reference it everywhere

The cleanest way to build this is as a single @graph: one block that defines the Person, the WebSite and anything else that exists sitewide, each with a stable @id. Every other node — an article, a project, a service — then points at those ids instead of describing the person again.

That discipline matters because a duplicate definition is not harmless. If a page defines the Person in one block and describes them slightly differently in another, a crawler has two competing claims about the same entity and no way to know which one you meant. One definition, many references.

sameAs: link only what you can verify both ways

The sameAs property asks a search engine to treat another URL as the same entity as this one, so it is only as good as the links in it. The ones that help are the ones the other side confirms: a GitHub profile that links back to your site, a LinkedIn page with the same name and location.

A dead link, a dashboard behind a login, or a profile that now redirects to your own domain does the opposite. It asks the crawler to confirm a claim that can never be confirmed. Prune the list the way you would prune dependencies.

Mark up only what the page shows

Structured data has to describe content a visitor can actually see on that page. FAQPage markup on a page with no visible questions, or a star rating with no real reviews behind it, falls under Google's guidance on misleading markup, and the consequence is a manual action against the site rather than the markup being quietly ignored. If you cannot point to it on the page, leave it out.

Validate ruthlessly

Run every page through Google's Rich Results Test and the Schema.org validator. A single malformed field can silently disqualify the whole block. In Next.js, generating JSON-LD from typed helper functions — rather than hand-written script tags — makes malformed output nearly impossible.

The two tools answer different questions. The Rich Results Test shows what Google Search can use; the Schema Markup Validator at validator.schema.org checks the vocabulary itself, including types Google ignores. Run both, and run them against the live URL rather than localhost, since that is the version a crawler reads.

What structured data will not do

It is not a ranking switch. Google has said structured data is not itself a ranking factor; what it does is remove ambiguity — who a page is about, what kind of thing it is, how it connects to everything else — and make a page eligible for richer results.

That clarity can help any system that reads the page, including the answer engines that have to decide which Bhavesh, or which Bhoi, you are. It rewards the same habit as everything else here: say one true thing, once, in a form a machine can't misread.

SEONext.js

Bhavesh Bhoi

Software Developer at Aina Tech Services LLP. Work with me

Elsewhere on the site

The ideas here get used rather than just written about — the projects are where the animation and performance work lives, and client work covers the production systems. If you want something built, services explains how that works, or just get in touch.

Read next

What Rebuilding Award-Winning Sites Taught Me →