Organization JSON-LD — Entity Graph for Agents

What is Organization JSON-LD?

Organization JSON-LD is a <script type="application/ld+json"> block on your homepage that declares your company or service as a schema.org Organization entity. It is the canonical way to tell machines: "this domain represents this named entity, and here are the other places that entity exists on the web."

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Acme Robotics",
  "url": "https://acme.example",
  "logo": "https://acme.example/logo.png",
  "description": "Industrial robots for warehouse automation.",
  "sameAs": [
    "https://github.com/acme-robotics",
    "https://www.npmjs.com/package/acme-sdk",
    "https://twitter.com/acmerobotics",
    "https://www.linkedin.com/company/acme-robotics"
  ]
}
</script>

What is sameAs?

sameAs is the linked-data declaration that says "the entity described here is the same entity as the one at these other URLs." It is how machines consolidate scattered surfaces (your GitHub, your npm package, your LinkedIn, your registry listings) into a single entity in their knowledge graph.

Without sameAs, each surface looks like an unrelated orphan to a crawler. With it, your authority and identity signals consolidate.

Why it matters for AI agents

LLM-driven assistants (ChatGPT browsing, Claude, Perplexity, Gemini via Google's index) rely heavily on entity resolution before they answer. When a user asks "what is acme.example?", the model:

Looks up the domain in its entity index
Pulls in all the surfaces marked sameAs — your code, your social, your packages, your registry listings
Builds a unified picture: "this is the company, here is what they ship, here is who runs them"

JSON-LD is the most agent-accessible structured data format — it survives HTML-to-text conversion that strips microdata attributes, and it is directly parseable JSON. Schema.org is the vocabulary every major model has trained on.

What agentgrade checks

Organization JSON-LD (optional) — A JSON-LD block on the homepage declares @type: Organization
sameAs entity links (optional) — The Organization block includes a sameAs array with at least two valid HTTPS URLs

Both checks are optional — they do not penalize a passing score if absent — but they are strongly recommended for any site that wants AI assistants to talk about it accurately.

What to link in sameAs

The point of sameAs is to list authoritative profiles for the same entity. Good candidates:

Code: your GitHub organization, your GitLab, your public repos
Packages: npm, PyPI, crates.io, Maven Central, RubyGems
Identity: X/Twitter, LinkedIn company page, Mastodon, Bluesky
Registries: Crunchbase, Wikidata, Wikipedia entry
Agent surfaces: your listing on the Model Context Protocol Registry, Smithery, the x402 Bazaar

Pick the surfaces that are public, canonical, and stable. Do not link to dashboards, login pages, or surfaces that gate the content.

Where to put it

In your homepage <head>. You can have multiple JSON-LD blocks — one for WebApplication or WebSite, one for Organization. Most rich-results tools handle both.

Spec maturity

Established standard. schema.org Organization and sameAs are mature, widely adopted, and supported by every major search engine and AI agent. Google's Rich Results Test validates them, and Google's Article on knowledge panels lists them as primary identity signals.

agentgrade