Jonomor

Article — Jonomor

JSON-LD Schema for AI Visibility — Complete Guide

By Ali Morgan · Published by Jonomor

What JSON-LD Is and Why It Matters

JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding structured data using JSON syntax. It is embedded in web pages inside <script type="application/ld+json"> tags, making entity information machine-readable without affecting the visible page content.

JSON-LD is the format recommended by Schema.org and Google for structured data implementation. It is also the format that AI answer engines most reliably parse when building entity representations. When a system like ChatGPT, Perplexity, or Gemini encounters JSON-LD on a page, it can extract entity names, types, relationships, and descriptions directly — without inferring them from prose.

This distinction is critical for AI Visibility. An entity defined only in unstructured text requires the AI to infer what it is, how it relates to other entities, and whether it is authoritative. An entity defined in JSON-LD has all of those facts declared explicitly. The AI's inference burden is reduced, and its confidence in the entity representation increases.

JSON-LD is one of the five core components of Answer Engine Optimization. Without it, the entity graph exists only in human-readable form. With it, the entity graph is machine-readable — and machine-readability is what determines whether an AI system can cite the entity with confidence.

Priority Schema Types for AI Visibility

Not all Schema.org types carry equal weight for AI Visibility. The following types, implemented in order, build a coherent entity graph that AI systems can parse, traverse, and use for citation decisions.

  • Organization

    Site-wide baseline

    Required: @id, name, url, description, founder, hasPart

    Declare in the root layout so it appears on every page. The @id uses a fragment identifier like /#organization. The founder field references the Person @id. hasPart lists all product entities by @id reference. Description should state what the organization does, not marketing language.

  • Person

    Site-wide baseline

    Required: @id, name, url, jobTitle, description, worksFor, knowsAbout

    Declare in the root layout alongside Organization and WebSite. The @id uses a path-based fragment like /ali-morgan#person. worksFor references the Organization @id — not an inline duplicate of the organization object. knowsAbout lists domain expertise as strings.

  • WebSite

    Site-wide baseline

    Required: @id, name, url, publisher

    Declare in the root layout. publisher references the Organization @id. The @id uses /#website. This declares the domain itself as an entity and connects it to the organization.

  • SoftwareApplication

    Product pages and ecosystem page

    Required: @id, name, url, description, applicationCategory, isPartOf, operatingSystem

    Each software product gets its own SoftwareApplication declaration with a unique @id on its domain. isPartOf references the parent Organization @id. The parent declares hasPart referencing the product @id. This creates the bidirectional product-organization relationship.

  • TechArticle

    Every content page

    Required: @id, headline, description, url, inLanguage, author, publisher, mainEntityOfPage, isPartOf

    Every article, insight, concept page, case study, and reference page should carry TechArticle schema. author and publisher must reference canonical @ids — never inline objects with just a name string. Do not include datePublished or dateModified unless the dates are accurate and known.

  • FAQPage

    Pages with Q&A content

    Required: @id, mainEntity (array of Question items)

    Each Question item must include acceptedAnswer with a text field. Questions should match the visible H3 or question heading on the page exactly. Answer text should be under 300 words per answer. FAQPage schema should be a separate JSON-LD block from TechArticle — do not combine them in one @id.

  • CollectionPage

    Index pages

    Required: @id, name, description, url, mainEntity (ItemList)

    Index pages (articles index, insights index, case studies index, definitions index) use CollectionPage with an ItemList as mainEntity. Each ListItem includes position, name, and url. This tells AI systems the page is a structured collection, not a single article.

  • CreativeWork

    Publication entities

    Required: @id, name, url, description, author, publisher, isPartOf

    Research publications, reports, and non-software creative outputs use CreativeWork. The type signals 'authored work' rather than 'software product' or 'service'. author references the Person @id. publisher references the Organization @id.

For detailed governance rules on how these types interact, see Schema Governance.

Implementation Rules

Schema implementation for AI Visibility follows strict rules. These are not suggestions — they are the conditions under which structured data produces reliable AI retrieval results rather than creating noise or contradictions in the entity graph.

  • Use @id references, not inline objects

    When an entity is already declared elsewhere in the schema graph, reference it by @id. Do not re-declare the entity with inline properties. A TechArticle's author should be { "@id": "https://www.jonomor.com/ali-morgan#person" } — not { "@type": "Person", "name": "Ali Morgan" }. Inline duplicates create competing entity definitions.

  • One canonical @id per entity, used everywhere

    Each entity gets exactly one @id assigned in the entity registry. That @id is used in every schema declaration that references the entity — on every domain, in every page. If the Organization @id is https://www.jonomor.com/#organization, every TechArticle publisher field, every product isPartOf field, and every cross-domain reference uses that exact string.

  • Deploy the baseline in the root layout

    Organization, Person, and WebSite schema should be declared in the root layout file so they appear on every page of the site. This ensures that any page an AI system visits contains the core entity graph. Per-page schema (TechArticle, FAQPage, etc.) is added on individual pages via additional JSON-LD script tags.

  • No synthetic dates

    Do not include datePublished or dateModified unless the dates are accurate and represent real publication events. Synthetic dates — generated at build time or set to arbitrary values — create false temporal signals. If no real date exists, omit the field entirely.

  • Description must match visible content

    The description field in schema should accurately reflect the visible content on the page. Do not stuff keywords into descriptions. Do not use descriptions that contradict or deviate from what a reader sees on the page. Schema-copy consistency is a trust signal.

  • Validate after implementation

    After deploying schema, validate using the Schema.org validator or Google's Rich Results Test. Zero validation errors is the minimum standard. Warnings should be reviewed and addressed where possible. Schema that produces errors is worse than no schema — it signals carelessness to AI systems.

Common Schema Mistakes That Degrade AI Visibility

  • Inline entity duplication

    Declaring author as { "name": "Ali Morgan" } instead of { "@id": "https://www.jonomor.com/ali-morgan#person" }. The inline version creates a new, disconnected entity declaration that competes with the canonical one.

    Fix: Always use @id references for entities that are declared elsewhere in the graph.

  • Missing bidirectional relationships

    A product site declares isPartOf pointing to the parent organization, but the parent organization's schema does not include hasPart pointing back to the product. The relationship is only declared from one side.

    Fix: Verify every relationship from both ends. If A declares isPartOf B, then B must declare hasPart A.

  • Inconsistent @id values

    Using https://www.jonomor.com/#organization on one page and https://www.jonomor.com/#organization on another. These are different strings and create different entities.

    Fix: Establish canonical @id values in the entity registry and use them verbatim everywhere. No www variants, no trailing slash variants.

  • Synthetic datePublished values

    Setting datePublished to the build date or an arbitrary date. This creates false temporal signals that do not represent actual publication events.

    Fix: Omit datePublished unless the date is accurate and represents a real event.

  • Keyword-stuffed descriptions

    Writing description fields like 'AI SEO AEO entity graph structured data authority signals' instead of a natural, accurate sentence describing the content.

    Fix: Write descriptions that match the visible content. One clear sentence that describes what the page covers.

  • Client-side-only schema injection

    Injecting JSON-LD via client-side JavaScript that runs after the initial page load. Some AI crawlers do not execute JavaScript and will not see the schema.

    Fix: Inject JSON-LD in server-rendered HTML. In Next.js, this means declaring schema in page components that render server-side.

  • sameAs with placeholder URLs

    Including sameAs with URLs that do not exist or that do not point to real, verified identity profiles for the entity.

    Fix: Include sameAs only for real, verified URLs. If no external profiles exist, omit sameAs entirely — an absent sameAs is less damaging than an incorrect one.

Frequently Asked Questions

What is JSON-LD?
JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding structured data using JSON syntax. It is the format recommended by Schema.org and Google for embedding machine-readable entity information in web pages. AI systems and search engines parse JSON-LD to understand what entities exist on a page and how they relate to each other.
Why does JSON-LD matter for AI Visibility?
JSON-LD encodes entity facts, relationships, and types in a format that AI systems can parse directly. Without JSON-LD, AI systems must infer entity information from unstructured text, which is error-prone and inconsistent. With JSON-LD, the entity graph is declared explicitly, reducing inference burden and increasing citation confidence.
Which JSON-LD schema types should I implement first?
The priority implementation order is: Organization (establishes the parent entity), Person (establishes the founder or operator), WebSite (declares the domain), then per-page types like SoftwareApplication, TechArticle, FAQPage, and CreativeWork as appropriate. Organization, Person, and WebSite should be in the root layout so they appear on every page.

Related