JSON-LD Basics for AI SEO: A Complete Introduction to Structured Data

What Is JSON-LD? Definition

JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding structured data using the JSON format. It allows you to embed machine-readable descriptions of entities -- people, organizations, articles, products, events -- directly into your HTML pages. When an AI model or search engine crawls your page, JSON-LD tells it: "This page is an article about X, written by Y, published by Z, on this date, covering these topics."

Here is the simplest possible JSON-LD block:

Three things define every JSON-LD block:

1. @context -- Always "https://schema.org". This tells parsers you are using the schema.org vocabulary.
2. @type -- The entity type you are describing: Article, Organization, Person, FAQPage, Product, and so on.
3. Properties -- Key-value pairs that describe the entity: headline, author, datePublished, description, etc.

The JSON-LD block lives inside a `

The JSON-LD version is cleaner, easier to maintain, and completely decoupled from your HTML structure. If your frontend team redesigns the page, the JSON-LD block does not change. If you need to add a new property, you edit one block instead of hunting through templates.

**Bottom line:** Use JSON-LD for all new structured data implementations. If you have existing Microdata or RDFa, it still works -- but consider migrating to JSON-LD when you next update those pages.

</div>

<div id="how-to-add-json-ld">

## How to Add JSON-LD to Your Website 

Adding JSON-LD is straightforward. Here is a step-by-step process that works for any website, from static HTML to WordPress to custom React apps.

### Step 1: Identify the entities on your page

Before writing any code, answer these questions about the page:

- **What type of content is this?** (Article, Product, FAQ, Service, Event)
- **Who created it?** (Person or Organization)
- **Who published it?** (Organization)
- **What is the page about?** (Topic, keywords, category)
- **Are there questions and answers?** (FAQ candidates)

### Step 2: Write the JSON-LD block

Start with the `@context` and `@type`, then fill in the properties. Here is a complete example for a blog post:

```json

Step 3: Place the block in your HTML

Add the `

```

Step 4: Validate (see the Testing section below)

Step 5: Deploy and monitor

After deploying, wait 2-5 days for AI crawlers to re-index the page, then check whether your AI visibility has changed. You can monitor this with your AI Visibility Score.

Platform-specific notes

• WordPress: Use Yoast SEO or Rank Math for automatic schema, plus a custom HTML block or plugin like "Insert Headers and Footers" for additional JSON-LD
• Shopify: Use the built-in structured data (limited) or a JSON-LD app like JSON-LD for SEO
• Static HTML: Add the script blocks directly to your templates
• React / Next.js: Use the next/head component or a library like next-seo to inject JSON-LD
• Server-side rendering: Generate JSON-LD dynamically from your CMS data

Essential Schema Types for AI SEO

Not all schema types are equally important for AI visibility. Below are the five you should implement first, in order of priority, with complete code examples.

1. Organization Schema

Organization schema establishes your brand as a recognized entity. It tells AI models: "This is a real company with a name, logo, address, and verified presence on these platforms." This is the foundation of entity authority in AI search.

Key properties for AI SEO:

• sameAs -- Links to your profiles on Wikipedia, Wikidata, LinkedIn, Crunchbase. This is how AI models cross-reference and verify your entity. See our detailed sameAs property guide.
• description -- A clear, factual one-sentence description. AI models often extract this directly.
• logo -- Required for brand recognition in rich results.

2. Article Schema (or TechArticle)

Article schema describes individual pieces of content. Use Article for general blog posts, TechArticle for technical guides, and NewsArticle for news. For a complete guide with all variations, see Article Schema Markup for AI SEO.

Key properties for AI SEO:

• author with sameAs -- Links the article to a real person entity, building E-E-A-T signals
• dateModified -- AI models prefer fresh, recently updated content
• proficiencyLevel -- Helps AI match your content to the right audience
• wordCount -- Signals content depth

3. FAQPage Schema

FAQPage is arguably the single most important schema type for AI SEO. It provides pre-formatted question-answer pairs that AI models can extract directly. Research shows that FAQ Schema improves AI content interpretation from 16% to 54%.

Writing FAQ answers for AI citation:

• Keep each answer between 50-150 words -- the ideal length for AI to quote
• Start with a direct answer, then provide supporting details
• Include specific numbers, names, and facts -- AI models prefer concrete information over vague statements
• Write the answer as if it is the complete response to the question, without requiring the surrounding page context

4. Person Schema

Person schema establishes author identity and expertise. In AI SEO, author authority directly influences whether AI models trust and cite your content. This ties into E-E-A-T signals that both Google and AI models evaluate.

5. BreadcrumbList Schema

BreadcrumbList tells AI models where a page sits in your site hierarchy. This helps AI understand the topical context and relationships between your pages.

Note: The last item (the current page) should NOT include an item URL -- this is intentional per Google's guidelines.

Testing and Validating Structured Data

Invalid JSON-LD is worse than no JSON-LD. Broken markup can confuse AI crawlers and prevent rich results. Always validate before deploying.

Tool 1: Google Rich Results Test

URL: search.google.com/test/rich-results

This is your primary testing tool. It shows:

• Whether Google can parse your structured data
• Which rich result types your page is eligible for (FAQ dropdowns, breadcrumbs, etc.)
• Errors (markup that will be ignored) and warnings (recommended improvements)

You can test by URL (live page) or by pasting code (pre-deployment testing).

Tool 2: Schema.org Validator

URL: validator.schema.org

The Schema.org Validator checks your markup against the full schema.org specification. It is stricter than Google's tool and will flag issues like:

• Properties that are valid schema.org but not supported by Google
• Type mismatches (e.g., using a Text value where a URL is expected)
• Deprecated properties

Tool 3: Google Search Console

After deploying structured data to production, check Google Search Console's "Enhancements" section. It reports:

• Pages with valid structured data
• Pages with errors or warnings
• Trends over time (are you gaining or losing valid pages?)

Validation checklist

Before deploying any JSON-LD block, verify:

• [ ] Valid JSON syntax (no trailing commas, no unquoted strings)
• [ ] @context is "https://schema.org" (not http)
• [ ] @type matches a real schema.org type
• [ ] Required properties are present (varies by type)
• [ ] URLs are absolute, not relative
• [ ] Dates are in ISO 8601 format (YYYY-MM-DD)
• [ ] No duplicate @type declarations for the same entity on the page
• [ ] The content in schema matches the visible content on the page

Common JSON-LD Mistakes

These are the errors we see most frequently when auditing websites for AI SEO readiness.

1. Invalid JSON syntax

The most basic error. JSON is strict -- a single missing comma or extra trailing comma breaks the entire block. AI crawlers will silently ignore malformed JSON-LD.

Wrong:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "My Article",
  "author": "John Smith",  // <-- Comments not allowed in JSON
}  // <-- Trailing comma after last property

Correct:

{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "My Article",
  "author": {
    "@type": "Person",
    "name": "John Smith"
  }
}

2. Missing required properties

Each schema type has required and recommended properties. If you declare an Article without a headline, or an Organization without a name, validators will flag errors and AI models may ignore the entire block.

Minimum required properties by type:

| Schema Type | Required Properties | |---|---| | Article | headline, author, datePublished, image | | Organization | name, url | | FAQPage | mainEntity (array of Question objects) | | Person | name | | BreadcrumbList | itemListElement (array of ListItem objects) |

3. Using string values instead of objects

A common mistake is writing "author": "John Smith" instead of nesting a Person object. While technically valid JSON-LD, the string version provides far less information to AI models.

Weak:

"author": "John Smith"

Strong:

"author": {
  "@type": "Person",
  "name": "John Smith",
  "url": "https://example.com/team/john-smith",
  "sameAs": ["https://linkedin.com/in/johnsmith"]
}

4. Schema content that doesn't match page content

If your JSON-LD says the author is "Jane Doe" but the visible page credits "John Smith," Google may flag this as a mismatch and ignore the markup. AI models may also deprioritize content with inconsistent signals. The structured data must reflect what is actually on the page.

5. Using http instead of https in @context

The context URL must be "https://schema.org" (with https). Using "http://schema.org" still works in most parsers but is deprecated and may cause validation warnings.

6. Forgetting to update dateModified

If you update an article's content but leave dateModified unchanged, AI models will treat it as stale. Always update dateModified when you make meaningful changes to the content.

7. Duplicate or conflicting schemas

Having two Organization schema blocks with different information on the same page confuses parsers. Each entity type should appear once per page, or be clearly distinguished (e.g., the publisher Organization vs. a mentioned Organization).

Advanced Schema Types for AI SEO

Once you have the five essential types implemented, these advanced schema types can further improve your AI visibility.

Speakable Schema

SpeakableSpecification tells AI voice assistants (and text-based AI models) which parts of your page are best suited for reading aloud or quoting directly. This is particularly relevant for voice-powered AI like Google Assistant and Siri.

The cssSelector property points to specific parts of your page. Use it to highlight:

• Key takeaways or executive summaries
• Definitions and core explanations
• Short, quotable answer paragraphs

HowTo Schema

HowTo schema describes step-by-step processes. AI models frequently cite how-to content, and this schema makes your steps easy to extract.

Product Schema

For e-commerce and SaaS sites, Product schema helps AI models understand and recommend your products when users ask comparison or recommendation questions.

Key tip for Product schema and AI SEO: Include a clear description that answers the question "What does this product do and who is it for?" AI models pulling product recommendations use this field heavily.

These advanced types work best when combined with the five essential schemas. Your page should always have Organization + Article/TechArticle + FAQPage as the foundation, with advanced types layered on top for relevant content. For a deeper look at how semantic HTML structure supports your schema markup, see our dedicated guide.