Concept — Structured Data
Structured Data
Definition
Structured data is machine-readable markup — specifically JSON-LD schema — that encodes entity facts, relationships, and types so that AI systems can parse them directly rather than inferring them from prose.
Prose describes entities to human readers. Structured data describes them to machines. When both are present and consistent, AI systems can confirm what they infer from text against what the schema declares explicitly — reducing uncertainty and increasing citation confidence.
Why JSON-LD
Schema.org supports three serialization formats: JSON-LD, Microdata, and RDFa. JSON-LD is the only format that should be used for AI Visibility purposes.
JSON-LD is injected as a separate script block — it does not require modifying HTML element attributes, and it can declare the complete entity graph in a single location rather than scattering declarations across page markup. This makes it easier to maintain consistency, validate, and audit.
In Next.js, JSON-LD should be injected server-side — either in the root layout for site-wide baseline schema, or in page components for page-specific schema — using the <script type="application/ld+json"> tag with server-rendered content.
Priority Schema Types
- OrganizationEntity page, root layout baseline
Required fields
@id, name, url, description, founder, hasPart
Declared in the root layout so it is present on every page. Extended per-page where needed.
- PersonFounder page, root layout baseline
Required fields
@id, name, url, jobTitle, description, worksFor, knowsAbout
worksFor must reference the Organization @id, not a duplicate inline entity. sameAs is optional — include only real identity profile URLs.
- SoftwareApplicationSoftware product pages and parent ecosystem page
Required fields
@id, name, url, description, applicationCategory, isPartOf
isPartOf must reference the Organization @id. operatingSystem: Web for web-based products.
- DefinedTermSetMethodology entities such as Guard-Clause
Required fields
@id, name, url, description
The correct type for entities that are frameworks or methodology systems rather than software or publications.
- CreativeWorkResearch publications and analysis resources
Required fields
@id, name, url, description, publisher, author
publisher and author must reference canonical @ids, not inline duplicates.
- TechArticleAll authority content and concept pages
Required fields
@id, headline, description, url, inLanguage, author, publisher, mainEntityOfPage
Do not include datePublished or dateModified unless the date is accurate and confirmed. Never use placeholder dates.
- FAQPageQ&A format content
Required fields
mainEntity (array of Question + Answer)
Question text must match the on-page heading. Answer text must be plain text, under 300 words, matching the on-page answer.
- WebSiteRoot layout baseline only
Required fields
@id, name, url, publisher
Declared once in the root layout. Never duplicated per-page.
@graph Architecture Rules
- Use @graph in the root layout
The root layout should inject a single @graph containing Organization, Person, and WebSite schema. This establishes the baseline entity graph present on every page.
- Extend, do not duplicate
Per-page schema extends the baseline by adding page-type schema (TechArticle, ProfilePage, CollectionPage). Never re-declare the Organization or Person entity in full on every page — reference them by @id.
- Never create alternate @id values
Every entity has exactly one @id. Using different @id values for the same entity on different pages creates fragmented entity representations that degrade retrieval confidence.
- Schema must be server-rendered
JSON-LD injected only via client-side JavaScript may not be reliably parsed by AI crawlers. Use server components or static injection in Next.js to ensure schema is present in the initial HTML response.
- Schema must match on-page copy
The entity name, description, and relationships in JSON-LD must match the on-page text. If the schema says one thing and the copy says another, the schema signal is degraded.
- Validate before publishing
Run all schema through the Schema.org validator and Google Rich Results Test before deployment. Validation errors — not warnings — must be resolved. Schema with type errors produces unreliable signals.
Validation
All structured data must be validated before deployment. Validation errors — not warnings — indicate schema that will be misread or ignored by parsers.
Common validation errors that degrade AI Visibility signals: incorrect @type assignments, @id values that do not resolve to a real URL, required properties missing from core entity types, and author/publisher fields that duplicate entity definitions rather than referencing them by @id.
Schema validation is covered in the AI Visibility Framework as part of Stage 2 (Schema Graph) and is scored in the AI Visibility Audit.
Relationship to AI Visibility
Structured data is Stage 2 of the AI Visibility Framework. It is the machine layer that encodes the entity architecture defined in Stage 1. Without it, AI systems must infer entity facts from prose alone — a weaker and less reliable signal. With it, entity relationships are explicit, machine-readable, and consistently declared across every page.