Fixing HowTo Schema Errors

What HowTo markup is, and what Google does with it now

HowTo is a schema.org type for instructions: a page that walks the reader through a task one step at a time, such as replacing a tap washer, setting up two-factor sign-in or planting a hedge. The markup is a HowTo object with a name and a step list. Each step is usually a HowToStep with the instruction in text, and long guides can group steps into HowToSection items.

In August 2023 Google limited HowTo rich results to desktop, and in September 2023 it stopped showing them altogether. At the same time it removed HowTo from the Rich Results Test and from the Search Console enhancement reports. That is why many site owners saw their step-by-step search results vanish, and why the Rich Results Test now says it detects no rich result items on a page that has perfectly good HowTo markup.

The markup has not become useless. It is still valid schema.org, other search engines read it, and AI answer engines use clearly ordered steps when they quote a page as a set of instructions. A clean HowTo block also keeps your audit reports honest: a broken block is reported every time the page is scanned and hides real problems in the noise.

When HowTo is the wrong type

• Cooking: a recipe uses Recipe, which has its own ingredients, cooking times and nutrition. Do not mark a recipe up as HowTo, and do not add both to the same page.
• Questions and answers: a list of questions with one answer each is FAQPage, not HowTo.
• A single tip or a list of ideas: "ten ways to save energy" is not a sequence of steps. It has no order and no finished result, so it is an article, not a HowTo.
• Advertising: instructions whose purpose is to sell a product, where the steps are "buy our product", are not HowTo content.

The fields HowTo needs

HowTo has two fields it cannot do without and a handful that make it useful. Most audit errors come from a missing step, a step with no text, or a duration written in the wrong format.

A correct block you can copy

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to replace a tap washer",
  "description": "Stop a dripping tap by fitting a new washer in about 30 minutes.",
  "image": "https://example.com/images/tap-washer.jpg",
  "totalTime": "PT30M",
  "estimatedCost": { "@type": "MonetaryAmount", "currency": "GBP", "value": "3" },
  "supply": [ { "@type": "HowToSupply", "name": "Replacement tap washer" } ],
  "tool": [
    { "@type": "HowToTool", "name": "Adjustable spanner" },
    { "@type": "HowToTool", "name": "Flat-head screwdriver" }
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "Turn off the water",
      "text": "Turn off the isolation valve under the sink, then open the tap to drain what is left in the pipe.",
      "url": "https://example.com/tap-washer#step-1",
      "image": "https://example.com/images/tap-washer-step-1.jpg"
    },
    {
      "@type": "HowToStep",
      "name": "Remove the tap head",
      "text": "Prise off the decorative cap, undo the screw beneath it and lift the head off the valve.",
      "url": "https://example.com/tap-washer#step-2"
    },
    {
      "@type": "HowToStep",
      "name": "Fit the new washer",
      "text": "Unscrew the headgear nut with the spanner, swap the old washer for the new one and reassemble the tap.",
      "url": "https://example.com/tap-washer#step-3"
    }
  ]
}
</script>

Each step has its own anchor in url. Give the matching heading or list item on the page the same id (here step-1, step-2 and step-3) so the link goes to the right place.

The errors you will see, and what each one means

These are the messages the Schema Markup Validator, older Search Console reports and the Schema Debugger give for HowTo, with the cause behind each one.

Durations, costs, supplies and tools

HowTo carries more typed values than most schema types, and each one has a format that validators check strictly.

Durations

totalTime, prepTime and performTime take an ISO 8601 duration. It starts with P (period); a T separates days from hours, minutes and seconds.

Cost

estimatedCost is either plain text or a MonetaryAmount. Use MonetaryAmount with a three-letter currency code and a numeric value written as a string or number without the currency sign. For a range, use minValue and maxValue in place of value.

Supplies and tools

A HowToSupply is used up by the task (a washer, paint, screws). A HowToTool is needed but kept (a spanner, a brush, a drill). Both need a name, and both take an array when there is more than one. Plain strings are allowed by schema.org, but typed objects are clearer and let you add a requiredQuantity to a supply.

Fixing JSON that cannot be read

An unparsable block is the worst HowTo error: the whole script is ignored, including every other type in the same block, such as your Organization, BreadcrumbList or Article. HowTo blocks are long, and long blocks break more often. Four mistakes cause almost all of them.

1. A comma after the last step

    { "@type": "HowToStep", "text": "Reassemble the tap." },
  ]      <-- the comma before ] breaks the JSON

JSON does not allow a comma after the last item in a list or the last field in an object. It happens when a step is deleted by hand and the comma before it is left behind.

2. Curly quotes

Editors and word processors turn " into “ and ”. JSON only accepts straight double quotes around names and values. Curly quotes are fine inside the text of a step, but never as the quotes that open or close a value.

3. A double quote inside a step

"text": "Set the dial to "Eco" and press start."          <-- broken
"text": "Set the dial to \"Eco\" and press start."        <-- fixed

Instructions often quote a button label or a setting name, so this is more common in HowTo than in any other type.

4. A line break inside the text

A raw line break inside a value ends the string. Keep each step's text on one line. If a step has several parts, split it into separate steps, or use a HowToStep with an itemListElement of HowToDirection items.

Making the steps match the page

Structured data must describe what the reader can see. Steps in the markup that are not on the page, are in a different order, or say something different from the visible instructions are treated as misleading markup, which can lead to a manual action that removes rich results from the whole site.

• Same steps, same order. If the page has seven steps, the markup has seven steps, in the same order. Do not add steps to the markup that the page does not show.
• Full text, not a summary. The text of each step can be the whole instruction the reader sees. A one-word step in the markup against a paragraph on the page is a mismatch.
• Images of the step, not the product. A step image should show that step being done. Reusing one product photo on every step adds nothing and can be reported as a mismatch.
• Steps behind tabs or accordions are fine as long as the reader can open them without leaving the page.
• Videos: if the instructions are in a video, add a video (VideoObject) to the HowTo, and use hasPart Clip items for the start time of each step.

The fix, step by step

Long guides: HowToSection and HowToDirection

A guide with forty steps under five headings reads better, and validates more cleanly, when the markup follows the same structure. HowToSection is a named group of steps; HowToDirection and HowToTip split one step into smaller parts.

"step": [
  {
    "@type": "HowToSection",
    "name": "Prepare the wall",
    "itemListElement": [
      { "@type": "HowToStep", "text": "Fill holes with filler and leave it to dry." },
      { "@type": "HowToStep", "text": "Sand the filled areas smooth." }
    ]
  },
  {
    "@type": "HowToSection",
    "name": "Paint",
    "itemListElement": [
      { "@type": "HowToStep", "text": "Cut in around the edges with a brush." },
      {
        "@type": "HowToStep",
        "itemListElement": [
          { "@type": "HowToDirection", "text": "Roll the first coat in a W pattern." },
          { "@type": "HowToTip", "text": "Keep a wet edge to avoid lap marks." }
        ]
      }
    ]
  }
]

• A HowToSection uses itemListElement, not step and not text.
• A HowToStep that uses itemListElement may leave out text; the directions carry the instruction.
• Do not nest a HowToSection inside another HowToSection. Keep one level of groups.
• Add position to steps only if you number them on the page; the order of the array already gives the order.

Stopping it from coming back

• One source. Decide which tool outputs HowTo across the site and switch HowTo output off in every other plugin and theme.
• Build it from the page. If the visible steps and the markup come from the same data, they cannot drift apart.
• Escape at output. Generate the JSON with json_encode() or JSON.stringify(), never by joining strings.
• Store durations as numbers. Keep minutes as a number in the CMS and convert to PT…M in the template, so an editor can never type "half an hour" into the markup.
• Test after updates. Plugin and theme updates are the most common cause of a new duplicate block. Re-run the Schema Debugger on one how-to page after each update.