HowTo schema looks simple. A name, a list of steps, each step with a position and a description. Most implementations pass JSON validation on the first try. Most also fail Google’s Rich Results Test or fail to produce the rich result even when validation passes. Five specific mistakes account for the majority of HowTo failures we audit.
The most common HowTo mistake we see: step entries with no position field. Without explicit positions, Google’s rich result parser falls back to source-order inference, which is unreliable for nested or templated content.
The broken version:
"step": [
{"@type": "HowToStep", "name": "First step", "text": "Do this."},
{"@type": "HowToStep", "name": "Second step", "text": "Then this."}
]
The fixed version:
"step": [
{"@type": "HowToStep", "position": 1, "name": "First step", "text": "Do this."},
{"@type": "HowToStep", "position": 2, "name": "Second step", "text": "Then this."}
]
Explicit positions cost nothing to add and prevent inference errors. Always include them.
We see this on blog posts where the writer wants both Article (for blog post attribution) and HowTo (for the procedural rich result) on the same page. The instinct is to nest them. The implementation that works is to put both in the same @graph as siblings, not nested.
The broken version (Article wrapping HowTo):
{
"@type": "Article",
"headline": "How to do X",
"mainEntityOfPage": {
"@type": "HowTo",
"step": [...]
}
}
The fixed version (both at top level inside @graph):
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Article",
"@id": "https://example.com/post/#article",
"headline": "How to do X"
},
{
"@type": "HowTo",
"@id": "https://example.com/post/#howto",
"name": "How to do X",
"step": [...]
}
]
}
The @id cross-reference is what lets Google understand the two schemas describe the same page in different ways.
A surprisingly common pattern: the name field and the text field on a step are the same string. This passes JSON validation. It also makes the step useless for rich result generation, because the rich result template needs both a short label (name) and a longer description (text) to display.
The broken version:
{"@type": "HowToStep", "position": 1, "name": "Add FAQPage schema to the page", "text": "Add FAQPage schema to the page"}
The fixed version:
{"@type": "HowToStep", "position": 1, "name": "Add FAQPage schema", "text": "Wrap the page's 4 to 7 visible FAQs in FAQPage JSON-LD. Validate via Google's Rich Results Test."}
The name is a short label. The text is the actual instruction. Treat them as different fields.
Google’s HowTo rich result requires a minimum number of steps to display (typically 2 to 3, though Google has not published the exact threshold). HowTo schemas with one step pass validation and never produce a rich result.
If your “how to” actually has one step, it is not a HowTo. It is an instruction. Use a different schema type (FAQPage with a single Q&A, or an Article with the instruction as the main body).
The same applies in the other direction: HowTo schemas with 20+ steps tend to be truncated in rich results. If your process is genuinely 20 steps long, break it into phases, ship each phase as its own HowTo, and link them as related content.
The HowTo rich result can display images per step. The image fields are optional, but if you include them, they must resolve to real URLs. The most common mistake: including image URLs that 404, are placeholder URLs from a template, or point to images blocked by robots.txt.
Broken:
"image": "https://example.com/placeholder.jpg"
Fixed: either include a real, reachable image URL with explicit width and height:
"image": {
"@type": "ImageObject",
"url": "https://example.com/step-1-real.jpg",
"width": 1200,
"height": 800
}
Or omit the field entirely. A missing field is better than a broken one.
The deeper version of mistake four: the page is not actually a how-to. It is a “what is X” page, a “best of” listicle, or a comparison article. Slapping HowTo schema on non-procedural content is the equivalent of telling Google the page is a procedure when it is not. Google’s rich result parser eventually catches this and either ignores the schema or downgrades trust in the brand’s structured data overall.
The fix is to use the right schema type for the content. Definitional content gets Article + DefinedTerm. Listicles get Article + ItemList. Comparisons get Article + FAQPage. HowTo is for procedural content where the user can follow a numbered sequence of actions.
Two tools to run on every HowTo schema before shipping:
Google’s Rich Results Test at https://search.google.com/test/rich-results. Paste the URL and check whether the HowTo rich result is displayed and whether there are warnings about missing fields.
Schema.org Validator at https://validator.schema.org/. Paste the JSON-LD directly. Confirm all required and recommended fields are present.
If either tool returns errors, fix them. If both pass but the rich result still does not display in production after 14 days, the most likely cause is one of the five mistakes above. Re-audit.
If you have HowTo schema deployed on your site, run each instance through the Rich Results Test. If the rich result does not display or warnings appear, work through the five mistakes above. The cleanest implementations on your tactical and procedural content are the ones most likely to get cited by AI engines that read HowTo as a strong structural signal.
If you want us to audit and fix your HowTo schema across the site, book the fit call. Productized SEO and AI search at $497 a month, no contract.
Related reading:
– Schema markup for AI search: a 2026 field guide
– Your Organization schema is probably costing you AI citations
– JSON-LD vs Microdata vs RDFa in 2026
– GEO 101: Generative Engine Optimization Explained