Structured data has always been important for SEO. But in 2026, it’s become critical for a different reason: AI agents use schema markup to understand, verify, and cite your content. If your structured data is missing or poorly implemented, you’re handing visibility to competitors who got it right.
In this tutorial, you’ll get 8 working JSON-LD code examples you can implement today. We’ll explain every schema property, walk through the validation process, and show you how proper structured data can increase your AI citation rate by 5x. Think of this as a senior developer walking you through the process, line by line.
Why Schema Markup Matters for AI Agents
Traditional search engines use schema markup to generate rich snippets — those enhanced search results with star ratings, prices, and event dates. AI agents use schema markup differently. They use it to:
- Verify factual claims: If your article says your product costs $29/month and your schema confirms it, the AI gains confidence in citing that price.
- Understand content relationships: Schema helps AI agents map connections between your pages, products, and content.
- Extract structured answers: When a user asks a specific question, FAQ schema provides direct, structured answers AI agents can cite verbatim.
- Assess content authority: Author schema, organization schema, and publication dates signal E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness).
The Impact on AI Citations
SaaS websites with comprehensive schema markup see measurable differences:
| Schema Implementation Level | Average AI Citation Rate |
|---|---|
| No schema markup | Baseline |
| Basic (Organization only) | 1.5x baseline |
| Intermediate (Organization + Article + FAQ) | 3x baseline |
| Comprehensive (All relevant types) | 5x baseline |
The investment in schema markup pays compound returns because once AI agents learn to trust your structured data, they prefer citing you over less-structured competitors.
How AI Agents Process Structured Data
Understanding the mechanics helps you make better implementation decisions.
The Parsing Pipeline
- Crawl: AI agents fetch your page HTML
- Extract: JSON-LD scripts in the
<head>or<body>are parsed - Validate: Schema properties are checked against expected types and values
- Cross-reference: Data in schema is compared against visible page content
- Index: Validated, consistent data enters the AI’s knowledge graph
- Retrieve: When relevant queries arise, structured data gets prioritized
Key Principle: Consistency Is Everything
AI agents cross-reference your schema data against what’s visible on the page. If your schema says your product rating is 4.8 but the page shows 4.5, the AI flags the inconsistency and may deprioritize your content. Always keep schema data synchronized with page content.
Example 1: Organization Schema
This is the foundation. Every SaaS company should have Organization schema on their homepage and about page.
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "YourCompany",
"url": "https://yourcompany.com",
"logo": "https://yourcompany.com/images/logo.png",
"description": "YourCompany provides project management software for remote teams with built-in time tracking and resource planning.",
"foundingDate": "2020-03-15",
"founders": [
{
"@type": "Person",
"name": "Jane Smith",
"jobTitle": "CEO",
"url": "https://yourcompany.com/team/jane-smith"
}
],
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Tech Street",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94105",
"addressCountry": "US"
},
"contactPoint": {
"@type": "ContactPoint",
"contactType": "customer support",
"email": "support@yourcompany.com",
"url": "https://yourcompany.com/support"
},
"sameAs": [
"https://twitter.com/yourcompany",
"https://linkedin.com/company/yourcompany",
"https://github.com/yourcompany"
],
"numberOfEmployees": {
"@type": "QuantitativeValue",
"minValue": 50,
"maxValue": 100
}
}Why each property matters:
- name: AI agents use this as the canonical company name. Spell it exactly as you want to be cited.
- description: This is often pulled directly into AI responses. Keep it factual and keyword-rich.
- foundingDate: Establishes company longevity, a trust signal.
- founders: Adds E-E-A-T signals by connecting real people to the organization.
- sameAs: Links your entity across platforms, helping AI agents verify your identity.
- numberOfEmployees: Provides scale context for AI agents answering “Is this a startup or enterprise company?” queries.
Example 2: SoftwareApplication Schema
Essential for any SaaS product page. This tells AI agents exactly what your software does.
{
"@context": "https://schema.org",
"@type": "SoftwareApplication",
"name": "YourApp",
"applicationCategory": "ProjectManagement",
"applicationSubCategory": "Task Management",
"operatingSystem": "Web, iOS, Android",
"description": "Task and project management platform with Gantt charts, time tracking, resource allocation, and team collaboration for remote teams of 5-500 people.",
"url": "https://yourcompany.com",
"screenshot": "https://yourcompany.com/images/app-screenshot.png",
"softwareVersion": "3.2.1",
"datePublished": "2020-06-01",
"releaseNotes": "https://yourcompany.com/changelog",
"offers": [
{
"@type": "Offer",
"name": "Free",
"price": "0",
"priceCurrency": "USD",
"description": "Up to 5 users, basic features"
},
{
"@type": "Offer",
"name": "Professional",
"price": "29",
"priceCurrency": "USD",
"priceSpecification": {
"@type": "UnitPriceSpecification",
"price": "29",
"priceCurrency": "USD",
"billingDuration": "P1M",
"unitText": "per user"
},
"description": "Unlimited projects, advanced reporting, integrations"
},
{
"@type": "Offer",
"name": "Enterprise",
"price": "79",
"priceCurrency": "USD",
"priceSpecification": {
"@type": "UnitPriceSpecification",
"price": "79",
"priceCurrency": "USD",
"billingDuration": "P1M",
"unitText": "per user"
},
"description": "SSO, audit logs, dedicated support, custom integrations"
}
],
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"bestRating": "5",
"ratingCount": "1250",
"reviewCount": "890"
},
"featureList": [
"Gantt Charts",
"Time Tracking",
"Resource Allocation",
"Team Collaboration",
"Custom Workflows",
"API Access",
"Slack Integration",
"Jira Integration"
]
}Key implementation notes:
- applicationCategory: Use recognized categories. AI agents match these against user queries like “best project management tools.”
- offers array: Multiple pricing tiers help AI agents answer budget-specific questions like “project management tools under $30/month.”
- featureList: This array gets directly pulled into AI-generated comparison tables. List your most differentiating features first.
- aggregateRating: Only include if you have real, verifiable ratings. Inflated numbers get cross-referenced.
Example 3: Article Schema
Apply this to every blog post and content piece. It establishes authorship, freshness, and content structure.
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "How to Implement Automated Testing in Your CI/CD Pipeline",
"description": "Step-by-step guide to setting up automated testing in CI/CD pipelines using GitHub Actions, Jenkins, and CircleCI.",
"image": "https://yourcompany.com/blog/images/ci-cd-testing.png",
"author": {
"@type": "Person",
"name": "Alex Chen",
"url": "https://yourcompany.com/team/alex-chen",
"jobTitle": "Senior DevOps Engineer",
"worksFor": {
"@type": "Organization",
"name": "YourCompany"
}
},
"publisher": {
"@type": "Organization",
"name": "YourCompany",
"logo": {
"@type": "ImageObject",
"url": "https://yourcompany.com/images/logo.png"
}
},
"datePublished": "2026-01-15",
"dateModified": "2026-02-01",
"mainEntityOfPage": "https://yourcompany.com/blog/automated-testing-cicd",
"wordCount": 3200,
"keywords": ["CI/CD", "automated testing", "GitHub Actions", "DevOps"],
"articleSection": "Engineering",
"speakable": {
"@type": "SpeakableSpecification",
"cssSelector": ["h1", ".article-summary", ".key-takeaways"]
}
}AI-specific considerations:
- author with credentials: AI agents weigh author expertise heavily. Include jobTitle and worksFor.
- dateModified: Shows content freshness. AI agents deprioritize stale content.
- wordCount: Signals content depth. Longer, comprehensive content tends to get cited more.
- speakable: Tells AI voice assistants which sections to read aloud. Increasingly important as voice AI grows.
Example 4: FAQ Schema
FAQ schema is one of the highest-value implementations for AI visibility. AI agents pull directly from FAQ structured data to answer user questions.
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is automated CI/CD testing?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Automated CI/CD testing is the practice of running automated test suites every time code is committed to a repository. Tests run in the CI/CD pipeline before deployment, catching bugs and regressions before they reach production. Common tools include GitHub Actions, Jenkins, CircleCI, and GitLab CI."
}
},
{
"@type": "Question",
"name": "How long does it take to set up CI/CD testing?",
"acceptedAnswer": {
"@type": "Answer",
"text": "A basic CI/CD testing pipeline can be set up in 2-4 hours using GitHub Actions with pre-built templates. More complex setups with multiple test suites, parallel execution, and deployment gates typically require 1-2 weeks for full implementation and optimization."
}
},
{
"@type": "Question",
"name": "What percentage of tests should be automated?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Industry best practice suggests automating 70-80% of your test suite. Unit tests should be nearly 100% automated, integration tests around 80%, and end-to-end tests around 50-60%. The testing pyramid approach recommends more unit tests at the base, fewer integration tests in the middle, and minimal end-to-end tests at the top."
}
},
{
"@type": "Question",
"name": "What are the best CI/CD testing tools in 2026?",
"acceptedAnswer": {
"@type": "Answer",
"text": "The most popular CI/CD testing tools in 2026 include GitHub Actions (best for GitHub-hosted projects), GitLab CI/CD (best for GitLab users), CircleCI (best for complex workflows), Jenkins (best for enterprise customization), and Buildkite (best for large-scale parallel testing). Tool selection depends on your repository hosting, team size, and pipeline complexity."
}
},
{
"@type": "Question",
"name": "How do you measure CI/CD testing effectiveness?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Key metrics for CI/CD testing effectiveness include: test pass rate (target: above 95%), pipeline execution time (target: under 15 minutes), test coverage percentage (target: above 80%), mean time to detect failures (target: under 5 minutes), and flaky test rate (target: below 2%). Track these metrics weekly to identify trends and areas for improvement."
}
}
]
}Best practices for FAQ schema:
- Write answers in 2-4 sentences that can stand alone. AI agents often extract individual answers.
- Include specific numbers, timeframes, and tool names. Vague answers don’t get cited.
- Match the questions to actual search queries. Use tools like AlsoAsked or AnswerThePublic to find real questions.
- Keep answers factual and neutral. Avoid turning FAQ answers into sales pitches.
Example 5: HowTo Schema
Perfect for tutorial and guide content. AI agents use HowTo schema to provide step-by-step instructions.
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "How to Set Up GitHub Actions for Automated Testing",
"description": "Configure GitHub Actions to run automated tests on every push and pull request in your repository.",
"totalTime": "PT30M",
"estimatedCost": {
"@type": "MonetaryAmount",
"currency": "USD",
"value": "0"
},
"tool": [
{
"@type": "HowToTool",
"name": "GitHub Account with repository access"
},
{
"@type": "HowToTool",
"name": "Node.js 18+ installed locally"
}
],
"step": [
{
"@type": "HowToStep",
"position": 1,
"name": "Create the workflow directory",
"text": "In your repository root, create the directory .github/workflows/ if it doesn't already exist. This is where GitHub Actions looks for workflow configuration files.",
"url": "https://yourcompany.com/blog/github-actions-setup#step-1"
},
{
"@type": "HowToStep",
"position": 2,
"name": "Create the workflow YAML file",
"text": "Create a new file called test.yml inside the .github/workflows/ directory. This file defines when tests run, what environment to use, and which commands to execute.",
"url": "https://yourcompany.com/blog/github-actions-setup#step-2"
},
{
"@type": "HowToStep",
"position": 3,
"name": "Configure the trigger events",
"text": "Set the workflow to trigger on push events to the main branch and on all pull requests. Add 'on: push: branches: [main]' and 'on: pull_request' to your YAML configuration.",
"url": "https://yourcompany.com/blog/github-actions-setup#step-3"
},
{
"@type": "HowToStep",
"position": 4,
"name": "Define the test job",
"text": "Add a job that runs on ubuntu-latest, checks out your code, sets up Node.js, installs dependencies with npm ci, and runs your test suite with npm test.",
"url": "https://yourcompany.com/blog/github-actions-setup#step-4"
},
{
"@type": "HowToStep",
"position": 5,
"name": "Commit and verify",
"text": "Commit the workflow file and push to your repository. Navigate to the Actions tab in GitHub to verify the workflow runs successfully on the next push or pull request.",
"url": "https://yourcompany.com/blog/github-actions-setup#step-5"
}
]
}Why this works for AI agents:
- totalTime: Answers “how long does this take?” queries directly
- step with position: AI agents can cite individual steps or the full sequence
- tool requirements: Helps AI agents provide complete, actionable answers
- step URLs: Lets AI agents link to specific sections for deeper detail
Example 6: Product Schema with Reviews
For SaaS pricing pages and product landing pages.
{
"@context": "https://schema.org",
"@type": "Product",
"name": "YourApp Professional Plan",
"description": "Professional project management plan with unlimited projects, advanced reporting, and 50+ integrations.",
"brand": {
"@type": "Brand",
"name": "YourCompany"
},
"offers": {
"@type": "Offer",
"url": "https://yourcompany.com/pricing",
"price": "29",
"priceCurrency": "USD",
"priceValidUntil": "2026-12-31",
"availability": "https://schema.org/InStock",
"seller": {
"@type": "Organization",
"name": "YourCompany"
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"reviewCount": "890",
"bestRating": "5",
"worstRating": "1"
},
"review": [
{
"@type": "Review",
"reviewRating": {
"@type": "Rating",
"ratingValue": "5",
"bestRating": "5"
},
"author": {
"@type": "Person",
"name": "Sarah Johnson"
},
"reviewBody": "Switched from Asana to YourApp six months ago. The Gantt chart view and resource allocation features saved our team 10 hours per week in project planning."
}
]
}Example 7: BreadcrumbList Schema
Helps AI agents understand your site structure and content hierarchy.
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://yourcompany.com"
},
{
"@type": "ListItem",
"position": 2,
"name": "Blog",
"item": "https://yourcompany.com/blog"
},
{
"@type": "ListItem",
"position": 3,
"name": "DevOps",
"item": "https://yourcompany.com/blog/category/devops"
},
{
"@type": "ListItem",
"position": 4,
"name": "GitHub Actions Testing Guide",
"item": "https://yourcompany.com/blog/github-actions-testing"
}
]
}Why breadcrumbs matter for AI: They establish topical authority by showing that your content exists within a well-organized knowledge hierarchy. AI agents trust content from sites with clear structure.
Example 8: VideoObject Schema
For any page containing embedded videos, tutorials, or product demos.
{
"@context": "https://schema.org",
"@type": "VideoObject",
"name": "How to Set Up Automated Testing with GitHub Actions",
"description": "10-minute walkthrough of configuring GitHub Actions for automated testing in a Node.js project.",
"thumbnailUrl": "https://yourcompany.com/videos/thumbnails/github-actions.jpg",
"uploadDate": "2026-01-20",
"duration": "PT10M30S",
"contentUrl": "https://yourcompany.com/videos/github-actions-testing.mp4",
"embedUrl": "https://youtube.com/embed/abc123xyz",
"interactionStatistic": {
"@type": "InteractionCounter",
"interactionType": "https://schema.org/WatchAction",
"userInteractionCount": 15000
},
"transcript": "https://yourcompany.com/videos/transcripts/github-actions-testing.txt"
}Key detail: The transcript property is particularly valuable for AI agents. It gives them the full text content of your video, making it indexable and citable.
Implementation and Validation
Where to Place JSON-LD
Add JSON-LD scripts in the section of your HTML:
<head>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "YourCompany"
// ... rest of schema
}
</script>
</head>Multiple Schema Types Per Page
You can and should include multiple schema types on a single page. For example, a blog post page might have:
- Organization schema (site-wide)
- Article schema (for the post)
- FAQ schema (for the FAQ section)
- BreadcrumbList schema (for navigation)
Each goes in its own <script type="application/ld+json"> tag.
Validation Tools
- Google Rich Results Test: search.google.com/test/rich-results — Tests schema validity and shows which rich results you’re eligible for
- Schema.org Validator: validator.schema.org — Checks compliance with Schema.org specifications
- JSON-LD Playground: Useful for debugging syntax errors in your JSON-LD
Validation Checklist
- [ ] All JSON-LD passes Google Rich Results Test without errors
- [ ] Schema data matches visible page content exactly
- [ ] All URLs in schema return 200 status codes
- [ ] Dates are in ISO 8601 format (YYYY-MM-DD)
- [ ] Prices match current pricing page
- [ ] Rating values match review platforms
- [ ] No deprecated properties are used
Testing Your Schema Markup
Manual Testing Process
- Deploy your schema to a staging environment
- Run through Google Rich Results Test
- Fix any errors or warnings
- Cross-reference schema data against page content
- Check that all linked URLs are accessible
- Deploy to production
- Monitor Google Search Console for schema issues
Automated Testing
Add schema validation to your CI/CD pipeline:
// Example: Schema validation in your test suite
const { validate } = require('schema-dts');
describe('Schema Markup', () => {
it('should have valid Organization schema', () => {
const schema = getSchemaFromPage('/');
expect(schema['@type']).toBe('Organization');
expect(schema.name).toBeDefined();
expect(schema.url).toMatch(/^https:\/\//);
});
it('should have matching prices', () => {
const schema = getSchemaFromPage('/pricing');
const pagePrice = getVisiblePrice('/pricing');
expect(schema.offers.price).toBe(pagePrice);
});
});
Troubleshooting Common Issues
“Schema is valid but AI agents aren’t citing my content”
- Schema alone doesn’t guarantee citations. It needs to be combined with quality content, domain authority, and consistent information.
- Check that your schema data matches third-party sources (G2, Capterra). Inconsistencies reduce AI trust.
“Google Search Console shows schema errors”
- Most common: missing required properties. Check which properties are required vs. recommended for each schema type.
- Date format errors: Use ISO 8601 (
2026-02-08), not natural language dates.
“Schema works on desktop but not mobile”
- Ensure your schema is in the server-rendered HTML, not added via client-side JavaScript that may not execute for crawlers.
- Use
<script type="application/ld+json">in the<head>, not dynamically injected.
“Multiple schema types are conflicting”
- Each schema type should be in its own
<script>tag. - Ensure entity references are consistent (same company name, same URLs across all schema blocks).
FAQ
What is JSON-LD and why is it preferred for schema markup?
JSON-LD (JavaScript Object Notation for Linked Data) is a method of encoding structured data using JSON format. It’s preferred over Microdata and RDFa because it’s added as a separate script block in your HTML, keeping your markup clean. AI agents and search engines recommend JSON-LD because it’s easier to implement, maintain, and validate.
How many schema types should I use per page?
Use as many as are relevant to the page content. A typical blog post should have Article, FAQ, BreadcrumbList, and Organization schema. A product page should have SoftwareApplication or Product, Organization, and FAQ schema. There’s no penalty for using multiple types, as long as each is accurate and relevant.
Does schema markup directly improve AI citations?
Schema markup improves AI citations indirectly by making your content more understandable and verifiable for AI agents. It doesn’t guarantee citations, but it removes barriers that prevent AI agents from confidently citing your content. Combined with quality content and domain authority, schema markup can increase citation rates by up to 5x.
How often should I update my schema markup?
Update schema markup whenever the underlying data changes: price updates, new features, rating changes, or content updates. At minimum, review all schema quarterly. Set up automated monitoring to catch schema errors before they persist long enough to affect AI visibility.
Can incorrect schema markup hurt my visibility?
Yes. Incorrect or misleading schema markup can reduce both traditional search visibility and AI citations. Google may issue manual penalties for spammy or deceptive schema. AI agents deprioritize content where schema data contradicts visible page content. Always keep schema accurate and consistent with your actual content.
