Skip to content
AVE StudioFor marketing agenciesENHU

Cookbook

Organization schema and sameAs: the minimal correct graph

The goal is not more fields. It is one resolvable identity: one node, one identifier, and only sameAs links that actually exist.

Updated ·

Organization JSON-LD is usually taught as a form to fill in — add the name, the logo, the address, done. From a machine-reading standpoint the field count is not what matters; what matters is whether the markup describes one identifiable thing, consistently, on every page. A sparse but coherent graph is worth considerably more than a rich one that argues with itself. This recipe covers the minimal correct shape, then the mistakes that do not merely weaken a field but undermine the credibility of the whole entity — those are the expensive ones. Choosing the name and confirming it off-site are separate procedures; what belongs here is what gets decided in the code of your own pages.

The procedure

  1. One Organization node with one stable @id

    Give the organization an `@id` — typically the root URL plus a fragment, such as `https://example.com/#org` — and use exactly that everywhere. The `@id` is what binds markup across pages into one entity. Different identifiers per page do not describe one company many times; they describe many companies once. One important limit: cross-document `@id` does not work the way people hope. A crawler reads each URL in isolation, so leaving a stub node on a page on the theory that "the details are on the homepage" means the stub IS the entity for whoever fetched that page.

  2. Include the minimum, and only what is true

    A working minimum: `name`, `url`, `logo`, `description`, plus whatever genuinely applies — `address`, `email`, `foundingDate`, `numberOfEmployees`. No field needs inventing: a missing value is skipped, while a false one costs the node its credibility. Put the canonical form in `name`, the same one you use in visible text and on every other surface; the gap between a legal name and a trading name is what `legalName` and `alternateName` are for, not something to resolve by alternating between them.

  3. Point sameAs only at live, authoritative profiles

    `sameAs` asserts "this other URL is also this entity". Your official profiles belong there — social accounts, professional databases, entity registries. Two rules. First, every URL must be live and yours; a `sameAs` pointing at a deleted or non-existent item is WORSE than none, because it is a broken identity claim that reflects on the whole node. We measured this on ourselves: a sibling domain kept advertising two identifiers that had since been deleted, and the fix never reached it because the rule lived in a code comment whose scope was one repository. Second, use the canonical form — if your site canonicalises to `www.`, the `sameAs` should say `www.` too, not a variant that redirects.

  4. Do not scatter the graph across documents

    Every page should carry the FULL node it references rather than an identifier stub. This looks redundant, and it is — but it is the only shape that works from every entry point. Other nodes on the page (article, breadcrumb, FAQ) may reference it by `@id` within that same document; across documents, assume no merging happens.

  5. Validate, but do not write for the validator

    Run the markup through a structured data checker and fix what it reports as an error. What not to do: add a field because the tool marks it "recommended". Several recommended fields are rich-result prerequisites rather than quality measures, and an invented value satisfies the validator while degrading your entity. A validator checks syntax; truthfulness is your job.

  6. Bind it to one source and guard it

    Generate the markup from one place instead of hand-writing it per page. Then add a check that reads the node back out of the served HTML and fails when `sameAs` gains an unknown URL or the `@id` changes. A hand-maintained graph does not decay because it is difficult; it decays because three people fix it three different ways on three pages.

Frequently asked questions

Should I use Organization or a more specific type?
Use the most specific subtype that is actually true — `ProfessionalService` or `LocalBusiness` if you are a place-based service, for instance. When unsure, `Organization` is always correct; an overly specific but inaccurate type is worse than a general accurate one. You can supply several types as an array when both genuinely apply.
How many sameAs entries should I have?
There is no target number, and volume is not the goal. As many as are genuinely yours, live, and verifiable. Five real profiles beat twenty where fifteen are abandoned or belong to someone else. `sameAs` is not link building: each entry is a claim you have to stand behind.
Does every page need Organization markup?
Every page where the organization is the publisher or author, yes — and as a full node rather than a stub. A crawler reads each URL separately, so if someone enters on a deep page, that page's markup is all they see. It is redundant, and that is exactly why it works.
Are logo and address required?
Not required, but `logo` and `address` are among the most commonly used fields and both are checkable facts, which makes them cheap and safe. If you have no physical address, do not invent one: a missing field is neutral, while a false one damages the credibility of the whole node.
What if a sameAs target no longer exists?
Remove it, and do not replace it with an invented identifier. If you no longer have an item in some registry, your canonical URL is the anchor — that is the correct state, not a gap. Keeping a link to a deleted item is the worst option available: it is an actively false claim.

Sources

  1. schema.org — Organization type. https://schema.org/Organization
  2. schema.org — sameAs property. https://schema.org/sameAs
  3. Google — general structured data guidelines. https://developers.google.com/search/docs/appearance/structured-data/sd-policies