How JSON-LD works, why AI systems need it to cite your site, and how to implement AIFDS blueprints using AI-generated prompts or manual templates. Start with the basics or jump to the reference.
JSON-LD (JavaScript Object Notation for Linked Data) is a way to embed structured data into your web pages. It lives inside a <script type="application/ld+json"> tag in your HTML and describes your content in a format that machines can read.
It uses the schema.org vocabulary — a shared dictionary that Google, Bing, and AI systems all understand. When you add JSON-LD to your page, you're not changing how it looks to humans. You're adding a structured description that machines can parse instantly.
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Your Company",
"url": "https://yoursite.com"
}
</script>
That's it. A script tag with a JSON object. Every JSON-LD block starts with @context (which vocabulary you're using) and @type (what kind of thing you're describing).
AI systems like ChatGPT, Perplexity, and Google's AI Overviews don't read your site the way a human does. They don't browse your homepage, scan your about page, or click through your navigation. They process your content programmatically — and structured data is the cleanest signal they have.
Here's what structured data gives AI that plain HTML doesn't:
Who are you? A business, a person, a product, an article? JSON-LD makes this explicit instead of forcing AI to guess from context.
Who wrote this article? What company publishes this site? Who founded this business? Structured data connects entities to each other.
What's the price? When was this published? Where are you located? JSON-LD provides concrete data points AI can extract without interpretation.
Ratings, credentials, author identities, social profiles — all the signals AI uses to decide whether to cite you or your competitor.
Without structured data, AI has to infer all of this from unstructured text. That's slow, unreliable, and often wrong. With JSON-LD, you hand AI the answers directly.
Every blueprint page gives you two ways to generate your JSON-LD. Pick whichever fits your workflow.
Every blueprint includes an implementation prompt you can copy into Claude, ChatGPT, Cursor, or any AI coding tool. The prompt asks for your business details in a numbered list and generates a complete, valid JSON-LD block with the correct fields for your industry and page type.
This is the fastest path. Go to the Blueprint Library, find your page type, click "View Prompt," copy it, and paste it into your AI tool.
Every blueprint also has a JSON-LD template with YOUR_* placeholders. Copy the template, replace every placeholder with your actual data, and paste it into your page.
Add the JSON-LD inside a <script type="application/ld+json"> tag in your page's <head>. It must be in the HTML source — not injected by JavaScript after page load. AI crawlers read the raw HTML.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Your Page Title</title>
<!-- Your JSON-LD goes here -->
<script type="application/ld+json" data-aifds="aifds.org">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Your Company",
"url": "https://yoursite.com"
}
</script>
</head>
<body>
<!-- Your page content -->
</body>
</html>
Use the AIFDS Validator to see exactly what AI systems can read from your page. You can also use Google's Rich Results Test or Schema.org's Validator to check for syntax errors.
Structured data isn't just for Google rich snippets anymore. Here's where it's being read right now:
ChatGPT, Claude, and Gemini pull from web content when answering questions. Structured data helps them extract accurate facts about your business.
Perplexity, Google AI Overviews, and Bing Copilot use structured data to build their answer cards and citation lists.
Autonomous agents that shop, book, and research on behalf of users rely heavily on structured product and service data to make decisions.
Google and Bing still use JSON-LD for rich snippets, knowledge panels, and local business results. It's the foundation of modern SEO.
The details behind how JSON-LD and schema.org work. Use this as a reference when building or debugging your structured data.
Every JSON-LD block needs two required fields:
@context — Always "https://schema.org". This tells the parser which vocabulary you're using.@type — What kind of thing you're describing: Organization, Product, BlogPosting, Person, etc.
The type determines which properties are valid. A Product can have a price. A Person can have a jobTitle. You can browse all available types at schema.org/docs/full.html.
Most real-world pages describe more than one thing. A blog post has an author, a publisher, and breadcrumbs. A product has a seller and a return policy. The @graph property lets you describe multiple connected entities in a single JSON-LD block.
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://yoursite.com/#org",
"name": "Your Company"
},
{
"@type": "WebSite",
"name": "Your Site",
"publisher": {
"@id": "https://yoursite.com/#org"
}
}
]
}
The @graph is an array. Each item is a separate entity. They connect to each other using @id references.
The @id property gives an entity a unique identifier. Other entities can then reference it without repeating all the data. Think of it like a foreign key in a database.
// Define the entity with an @id
{
"@type": "Person",
"@id": "https://yoursite.com/#author",
"name": "Jane Smith",
"jobTitle": "Editor"
}
// Reference it from another entity
{
"@type": "BlogPosting",
"headline": "My Article",
"author": {
"@id": "https://yoursite.com/#author"
}
}
The convention is to use your domain plus a hash fragment: https://yoursite.com/#author, https://yoursite.com/#org, https://yoursite.com/#website. These don't need to be real URLs — they're just unique identifiers.
Here are the types you'll use most often, organized by what they describe:
Organization, ProfessionalService, LocalBusiness (and subtypes like Restaurant, Dentist, Store)
Person — used for authors, founders, staff. Includes name, jobTitle, sameAs (social links), worksFor
BlogPosting, NewsArticle, Article, Blog, WebPage
Product, Offer, SoftwareApplication, AggregateRating, Brand
BreadcrumbList, ListItem, WebSite
PostalAddress, GeoCoordinates, ContactPoint, OpeningHoursSpecification
These are the errors we see most often. Avoiding them puts you ahead of most sites.
If your JSON-LD is added to the page by client-side JavaScript (React, Vue, etc.), many AI crawlers won't see it. They read the raw HTML source. Your structured data must be in the HTML before any JS executes.
A BlogPosting is not the same as a NewsArticle. A ProfessionalService is not the same as a LocalBusiness. Using the wrong type confuses AI about what your content actually is. Check our blueprints for the right type.
If you define a Person as an author but don't give it an @id, other entities can't reference it. Without @id linking, AI sees isolated data instead of connected entities.
Having multiple JSON-LD blocks that describe the same entity with different data (different addresses, different names) creates confusion. One block per page using @graph keeps everything consistent.
Shipping a page with "name": "YOUR_BUSINESS_NAME" is worse than having no structured data at all. Always replace every placeholder before going live.
Each page should describe itself. A blog post page describes that article and its author. A product page describes that product. Don't dump your full site schema on every page — it dilutes the signal.