How to Fix Schema References

Schema references are how you connect entities. An Article references its publisher Organization. A Product references its brand. A Person references their employer. Each reference needs a target — either an entity defined elsewhere on the page, or an external URI via sameAs. Broken references mean those connections silently disappear. This guide covers within-page references via @id, cross-page references for entity continuity, and external references via sameAs for knowledge graph anchoring.

1. Audit references

# Find @id values referenced on the page
grep -oP '"@id":\s*"[^"]+"' page.html | sort -u

# Compare what's defined vs what's referenced
# Anything referenced but not defined = broken reference

2. Fix within-page references

Broken: reference without definition

{
  "@type": "Article",
  "publisher": { "@id": "https://acme.com/#organization" },
  "author": { "@id": "https://acme.com/team/jane#person" }
}
// Neither Organization nor Person defined on this page → broken

Fixed: define both inline OR ensure defined in @graph

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://acme.com/#organization",
      "name": "Acme Co",
      "url": "https://acme.com"
    },
    {
      "@type": "Person",
      "@id": "https://acme.com/team/jane#person",
      "name": "Jane Doe",
      "url": "https://acme.com/team/jane"
    },
    {
      "@type": "Article",
      "publisher": { "@id": "https://acme.com/#organization" },
      "author": { "@id": "https://acme.com/team/jane#person" }
    }
  ]
}

3. Cross-page entity continuity

The same Organization @id appears on every page. Same Person @id on every article they wrote. Search engines correlate references across pages.

Template the Organization graph node

// shared/organization.json
{
  "@type": "Organization",
  "@id": "https://acme.com/#organization",
  "name": "Acme Co",
  "url": "https://acme.com",
  "logo": {
    "@type": "ImageObject",
    "@id": "https://acme.com/#logo",
    "url": "https://acme.com/logo.svg",
    "width": 600,
    "height": 60
  },
  "sameAs": [
    "https://en.wikipedia.org/wiki/Acme_Co",
    "https://twitter.com/acmeco",
    "https://www.linkedin.com/company/acmeco"
  ]
}

// Every page includes this in its @graph

4. sameAs for external entities

sameAs is how you tell search engines "this entity I'm describing here is the same as the entity already known at these other URIs". Builds your entity into the knowledge graph.

Organization sameAs

{
  "@type": "Organization",
  "@id": "https://acme.com/#organization",
  "name": "Acme Co",
  "sameAs": [
    "https://en.wikipedia.org/wiki/Acme_Co",
    "https://www.wikidata.org/wiki/Q12345",
    "https://www.crunchbase.com/organization/acme-co",
    "https://twitter.com/acmeco",
    "https://www.linkedin.com/company/acmeco",
    "https://www.facebook.com/acmeco",
    "https://www.youtube.com/@acmeco",
    "https://github.com/acmeco"
  ]
}

Person sameAs

{
  "@type": "Person",
  "@id": "https://acme.com/team/jane#person",
  "name": "Jane Doe",
  "jobTitle": "Chief Engineering Officer",
  "worksFor": { "@id": "https://acme.com/#organization" },
  "sameAs": [
    "https://en.wikipedia.org/wiki/Jane_Doe",
    "https://www.linkedin.com/in/janedoe",
    "https://twitter.com/janedoe",
    "https://github.com/janedoe",
    "https://orcid.org/0000-0000-0000-0000"
  ]
}

Place sameAs

{
  "@type": "Place",
  "name": "Acme HQ",
  "address": { ... },
  "sameAs": [
    "https://www.google.com/maps/place/...",
    "https://www.openstreetmap.org/way/123456"
  ]
}

5. Validate sameAs URLs

# Quick check
for url in $(grep -oP 'https://[^"]+' sameAs-list.txt); do
  status=$(curl -s -o /dev/null -w "%{http_code}" "$url")
  echo "$status $url"
done

# Anything not 200 needs review

6. Brand to Wikidata

Wikidata is the structured equivalent of Wikipedia. Even entities without Wikipedia articles often have Wikidata entries. Adding a Wikidata sameAs gives search engines a strong anchor.

"sameAs": [
  "https://www.wikidata.org/wiki/Q12345"
]

7. Author entity per article

Article rich results increasingly favour pages with strong author entity signals. Define each author as a Person with @id, sameAs, and worksFor:

{
  "@type": "Person",
  "@id": "https://yoursite.com/authors/jane-doe#person",
  "name": "Jane Doe",
  "url": "https://yoursite.com/authors/jane-doe",
  "image": "https://yoursite.com/authors/jane-doe.jpg",
  "jobTitle": "Senior Reporter",
  "worksFor": { "@id": "https://yoursite.com/#organization" },
  "sameAs": [
    "https://www.linkedin.com/in/janedoe",
    "https://twitter.com/janedoe",
    "https://muckrack.com/jane-doe"
  ]
}

Author pages help — a published profile URL means Google can verify and accumulate signals over time. Anonymous or generic "Admin" authors get fewer rich-result placements.

8. Verify