How to Add Schema Markup with Yoast SEO
Configure Yoast SEO’s Schema graph, add FAQ and HowTo markup, validate your output, and fix the most common structured-data problems.
Short answer: Yoast SEO adds Schema.org structured data automatically. Configure whether your site represents a person or organization, keep Yoast’s Schema Framework enabled, choose accurate content-type defaults, and use the FAQ or HowTo blocks only when the visible page really contains those elements. Then inspect the rendered JSON-LD and validate it.
Yoast describes its output as a connected Schema graph rather than isolated snippets. That graph can include WebPage, Article, Organization or Person, BreadcrumbList, ImageObject, FAQPage, HowTo, Product, Review, and integration-specific pieces, depending on your settings and content. See Yoast’s implementation guide for the model.
1. Configure the site representation
Open the WordPress admin and go to Yoast SEO → Settings. Set the site representation to the entity that owns the site:
- Organization: use this for a company, publication, school, nonprofit, or other organization. Add the organization name and logo when Yoast asks for them.
- Person: use this for a personal site or a site centered on one author.
This information supplies the entity context that other nodes in the graph can reference. Keep names, logos, author profiles, and URLs consistent with what visitors see on the site.
2. Leave Yoast’s Schema Framework enabled
Go to Yoast SEO → Settings → Advanced → Schema and confirm that the Schema Framework is on. Yoast says the enabled framework builds one connected Schema graph and strongly recommends leaving it enabled. Turning it off can remove the graph that ties your page, author, publisher, and breadcrumb entities together.
3. Set accurate defaults for posts and pages
In the content-type settings, review the defaults for Posts and Pages. Yoast’s defaults are:
| WordPress content | Default Yoast description | When to change it |
|---|---|---|
| Pages | WebPage |
Only when the page is a different supported type and the visible content matches it. |
| Posts | Article plus WebPage |
When a post is genuinely another supported content type, such as a product or a special landing page. |
Yoast documents these defaults in its content-type Schema settings. A global default does not overwrite a post or page that already has an individual non-default setting.
4. Override Schema for one page when necessary
- Open the post or page in the block editor.
- Open the Yoast SEO sidebar or meta box.
- Find the Schema controls and choose the most accurate supported type for that item.
- Update the page and review the rendered source.
Use an override when one item differs from the site-wide pattern. Do not select a type simply because it sounds useful for search visibility. The type must describe content that is actually present and visible on the page.
5. Add FAQ schema with the Yoast FAQ block
Use the Yoast FAQ block when the page contains a real set of questions and their answers:
- Edit the page with the WordPress block editor.
- Insert the Yoast FAQ block.
- Add each question and its complete answer.
- Publish or update the page.
The block adds the corresponding FAQ structured-data pieces automatically. Keep every question and answer visible to readers. Do not label an ordinary article as FAQPage when it does not contain a genuine question-and-answer section; inaccurate markup can create validation problems or unexpected search behavior.
6. Add HowTo schema with the Yoast HowTo block
For a genuine step-by-step tutorial, insert the Yoast HowTo block and enter the same steps that visitors can read on the page. Include the instructions, step names, and any images or tools that are part of the visible tutorial. The structured data should describe the page, not hidden instructions written only for crawlers.
Yoast’s structured-data blocks provide the FAQ and HowTo pieces. If the page is not an FAQ or a procedure, keep its normal Article or WebPage description.
7. Implement breadcrumbs when they help navigation
Breadcrumbs are useful when they reflect the site’s actual hierarchy. Configure them under Yoast SEO → Settings → Advanced → Breadcrumbs, then add the breadcrumb display code or block according to Yoast’s implementation instructions. When enabled and displayed, Yoast outputs BreadcrumbList JSON-LD in the page source. Search engines may use that data for breadcrumb displays.
Check the visual breadcrumb trail as well as the JSON-LD. A breadcrumb graph that does not match the links users can follow is a content problem, not a validation problem to hide.
8. Inspect the JSON-LD that WordPress actually renders
Always inspect the published response, because caching, themes, integrations, and per-page overrides can change the final graph.
Browser check
- Open the published URL in a private window.
- View source (not only the DOM inspector).
- Search for
application/ld+jsonand@graph. - Confirm that the graph contains the expected page, author or publisher, and optional FAQ, HowTo, or BreadcrumbList nodes.
cURL check
curl -L "https://example.com/your-page/" \
| grep -o ''Python check
import json
import requests
from bs4 import BeautifulSoup
url = "https://example.com/your-page/"
html = requests.get(url, timeout=30).text
soup = BeautifulSoup(html, "html.parser")
for tag in soup.select('script[type="application/ld+json"]'):
try:
data = json.loads(tag.string or tag.get_text())
print(json.dumps(data, indent=2))
except json.JSONDecodeError:
print("Invalid JSON-LD block")Node.js check
const url = 'https://example.com/your-page/';
const html = await (await fetch(url)).text();
const matches = [...html.matchAll(/<script[^>]+type=["']application\/ld\+json["'][^>]*>([\s\S]*?)<\/script>/gi)];
for (const match of matches) {
try {
console.log(JSON.stringify(JSON.parse(match[1]), null, 2));
} catch {
console.error('Invalid JSON-LD block');
}
}The Node example uses the response body directly. If your environment does not provide global fetch, use a current Node release or install an HTTP client.
9. Validate and review the graph
- Check that the selected type matches visible content.
- Check required properties reported by the validator for the selected type.
- Check that URLs, names, images, authors, and dates are correct.
- Check that FAQ answers and HowTo steps are present on the page.
- Check for duplicate JSON-LD from another SEO plugin, theme, or custom code.
Validation confirms syntax and supported properties; it does not guarantee a rich result or a ranking increase. Yoast’s documentation describes structured data as helping search engines understand pages and making them eligible for supported displays, without publishing a guaranteed numerical uplift.
10. Integrations and custom extensions
Yoast lists integrations for The Events Calendar, Seriously Simple Podcasting, WP Recipe Maker, Yoast WooCommerce SEO, and Easy Digital Downloads. Enable and configure an integration only when its content is present.
For custom entities, use Yoast’s documented Schema API and filters so additions join the existing graph. Avoid printing a second, disconnected graph from a theme or plugin. A custom extension should reference the existing entity IDs and preserve the relationships that make the graph coherent.
Common errors and fixes
| Symptom | Likely cause | Fix |
|---|---|---|
| No JSON-LD appears | The framework is disabled, a cache serves stale HTML, or another plugin removed output. | Re-enable the Schema Framework, purge page and CDN caches, then inspect the published source. |
| FAQ or HowTo is missing | The page uses ordinary headings instead of the Yoast block, or the block is not rendered in the published template. | Use the matching Yoast block and verify its output in view source. |
| Duplicate Article or Organization nodes | Another SEO plugin, theme, or custom snippet emits its own graph. | Choose one owner for the graph and integrate custom pieces through Yoast’s API. |
| Validation says the type is inaccurate | The selected type does not match the visible page. | Change the per-page Schema setting or rewrite the content so the type is truthful. |
| Breadcrumbs validate but do not display | The JSON-LD exists, but the breadcrumb template or block is not rendered. | Implement the visible Yoast breadcrumb output and confirm its hierarchy. |
| Changes are not visible | WordPress, plugin, CDN, or browser cache is serving an older response. | Purge each cache layer and fetch the canonical URL again. |
| Rich result does not appear | Eligibility is not a guarantee of display; the content, query, or search feature may not qualify. | Keep the markup accurate, fix reported issues, and avoid promises about rankings. |
Performance, reliability, and maintenance
- Performance: JSON-LD is small compared with page media, but duplicate graphs add unnecessary HTML. Keep one connected graph.
- Reliability: Prefer Yoast’s settings and blocks over hand-maintained snippets. Recheck output after theme, plugin, template, or permalink changes.
- Editorial maintenance: Update schema when the visible author, publisher, breadcrumbs, FAQ answers, product data, or procedure changes.
- Deployment checks: Fetch representative post, page, FAQ, HowTo, and breadcrumb URLs after releases and compare their rendered graph.
- Cost: Yoast’s automatic graph does not require a separate schema service. Premium schema blocks and add-ons are described in Yoast’s feature material; choose them only when their supported content matches your needs.
Or skip the browser setup
If your goal is to capture the finished page for documentation, QA, or an editorial workflow, ScreenshotNeo returns a screenshot or PDF from one GET request. It accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the page verdict and billing status in X-Page-Verdict and X-Billed headers. Its MCP server also lets Claude, Cursor, and other MCP clients call take_screenshot, get_page_info, and capture_pdf.
Read the ScreenshotNeo API documentation for all capture options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com/your-page/ -o yoast-schema.webpimport requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://example.com/your-page/"}, timeout=90)
open("yoast-schema.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://example.com/your-page/' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);There are 1,000 screenshots per month free with no card; paid plans start at $5 for 3,000. Create a free ScreenshotNeo account.
FAQ
Does Yoast SEO add Schema automatically?
Yes. Yoast automatically outputs Schema.org data appropriate to your page types when its Schema Framework is enabled and your site information is configured.
Should every post use Article schema?
No. Use the type that accurately describes the content. Yoast’s default for posts is Article plus WebPage, but individual content can use another supported type when appropriate.
Can I add FAQ schema with normal headings?
Use the Yoast FAQ block for FAQ structured data and keep the questions and answers visible on the page.
Will schema markup improve rankings?
It can help search engines understand content and may support eligible search features, but Yoast does not publish a guaranteed ranking increase.
Should I write a separate JSON-LD graph?
Usually no. Avoid duplicate output and use Yoast’s Schema API or documented filters when a custom graph piece is necessary.
