No HowTo schema on a tutorial page

What Is This Issue

Tutorial or step-by-step guide pages are missing HowTo schema, reducing eligibility for Google’s step-expansion rich results and voice search step readout.

Without HowTo schema:

Google can’t display an expanded step list directly in search results
Voice assistants can’t read steps aloud sequentially
Step-by-step content won’t be eligible for rich results
Users can’t see the process overview before clicking
AI search engines can’t properly understand instructional content

A proper HowTo schema should include: @type (HowTo), name, step (array of HowToStep items), and optionally totalTime, supply, tool, image.

Why Is This Important

HowTo schema is important for instructional content visibility:

Step-expansion rich results: Google can display an expanded step list directly in SERPs
Voice search: Voice assistants can read steps aloud sequentially
User engagement: Users can see the process overview before clicking
AI search readiness: AI engines use HowTo schema to understand and cite instructional content
Featured snippets: Step-by-step content may appear in featured snippets
Visual appeal: Including images for each step increases rich result eligibility

Resolving this issue improves your SEO health score by ensuring instructional content is properly structured for maximum visibility.

How XeoPix Detects This

XeoPix follows these logical steps to detect missing HowTo schema:

Detect how-to pages: The crawler identifies pages with:
- How-to URL patterns (/how-to/, /tutorial/, /guide/, /steps/)
- Numbered step lists (e.g., “1.”, “2.”, “3.” or “Step 1”, “Step 2”)
- Titles starting with “How to”, “Steps to”, “Guide to”, “Tutorial”
Extract structured data: The crawler looks for JSON-LD, Microdata, or RDFa blocks on the page
Check for HowTo schema: The crawler verifies if any schema block has:
- @type set to HowTo
- step property containing an array of HowToStep items
Validate schema completeness: If HowTo schema is found, the crawler checks for:
- step array with at least one HowToStep
- Each HowToStep has name and/or text property
- totalTime in ISO 8601 duration format (recommended)
Trigger conditions: The issue is flagged when:
- Page has step-by-step content but no HowTo schema
- HowTo schema exists but step array is empty or missing

How To Fix

Identify how-to pages: Look for pages with:
- How-to URL patterns (/how-to/, /tutorial/, /guide/)
- Numbered step lists
- Titles starting with “How to”, “Steps to”, “Guide to”

Add HowTo JSON-LD structured data to the page’s <head> or before </body>:


{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Change a Car Tyre",
  "totalTime": "PT30M",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Loosen lug nuts",
      "text": "Before lifting the car, loosen the lug nuts slightly.",
      "image": "https://example.com/step1.jpg"
    },
    {
      "@type": "HowToStep",
      "name": "Jack up the car",
      "text": "Position the jack under the vehicle frame and raise it.",
      "image": "https://example.com/step2.jpg"
    },
    {
      "@type": "HowToStep",
      "name": "Remove the flat tyre",
      "text": "Fully remove the lug nuts and take off the flat tyre.",
      "image": "https://example.com/step3.jpg"
    }
  ]
}

Include required properties:
- name: How-to title
- step: Array of HowToStep items
Add recommended properties:
- totalTime: In ISO 8601 duration format (PT30M = 30 minutes)
- image: For each step (increases rich result eligibility)
- supply: List of supplies needed
- tool: List of tools needed
Only use on genuine instructional content (not for marketing or sales pages)
Validate with Google’s Rich Results Test

What We Store

Storage Level

Page Level — This issue is evaluated for each individual URL that contains structured data.

Database Table / Prisma Model

PageStructuredData

Stored Fields

Field	Type	Description
schemaType	SchemaType	The type of schema (e.g., Organization, Person)
schemaFormat	SchemaFormat	The format of the schema (JSON-LD, Microdata, RDFa)
schemaIdentifier	String?	Unique identifier for the schema
rawJson	Json?	The raw JSON-LD or structured data content
schemaErrors	Json?	Array of validation errors found in the schema
isValidSchema	Boolean?	Whether the schema is valid according to validation
missingFields	Json?	Array of required fields that are missing

Detection Dependencies

The following data sources are required to evaluate this issue:
HTML Document — The crawler parses the HTML to find structured data (JSON-LD, Microdata, RDFa)
Structured Data Validation — The extracted schema is validated against Schema.org definitions
Schema Parser — JSON-LD scripts, Microdata attributes, and RDFa markup are parsed

Examples

Example 1: Missing HowTo Schema on Tutorial Page

Problematic state:


<!-- Tutorial page without HowTo schema -->
<html>
  <head>
    <title>How to Change a Car Tyre</title>
  </head>
  <body>
    <h1>How to Change a Car Tyre</h1>
    <h2>Step 1: Loosen lug nuts</h2>
    <p>Before lifting the car, loosen the lug nuts slightly.</p>
    <h2>Step 2: Jack up the car</h2>
    <p>Position the jack under the vehicle frame and raise it.</p>
    <h2>Step 3: Remove the flat tyre</h2>
    <p>Fully remove the lug nuts and take off the flat tyre.</p>
  </body>
</html>

Corrected state:


<!-- Tutorial page with HowTo schema -->
<html>
  <head>
    <title>How to Change a Car Tyre</title>
    <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "HowTo",
        "name": "How to Change a Car Tyre",
        "totalTime": "PT30M",
        "step": [
          {
            "@type": "HowToStep",
            "name": "Loosen lug nuts",
            "text": "Before lifting the car, loosen the lug nuts slightly.",
            "image": "https://example.com/step1.jpg"
          },
          {
            "@type": "HowToStep",
            "name": "Jack up the car",
            "text": "Position the jack under the vehicle frame and raise it.",
            "image": "https://example.com/step2.jpg"
          },
          {
            "@type": "HowToStep",
            "name": "Remove the flat tyre",
            "text": "Fully remove the lug nuts and take off the flat tyre.",
            "image": "https://example.com/step3.jpg"
          }
        ]
      }
    </script>
  </head>
  <body>
    <h1>How to Change a Car Tyre</h1>
    <h2>Step 1: Loosen lug nuts</h2>
    <p>Before lifting the car, loosen the lug nuts slightly.</p>
    <h2>Step 2: Jack up the car</h2>
    <p>Position the jack under the vehicle frame and raise it.</p>
    <h2>Step 3: Remove the flat tyre</h2>
    <p>Fully remove the lug nuts and take off the flat tyre.</p>
  </body>
</html>

Example 2: HowTo Schema with Supplies and Tools

Corrected state with supplies and tools:


{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Bake Chocolate Chip Cookies",
  "totalTime": "PT45M",
  "supply": [
    { "@type": "HowToSupply", "name": "2 cups flour" },
    { "@type": "HowToSupply", "name": "1 cup chocolate chips" },
    { "@type": "HowToSupply", "name": "1/2 cup sugar" }
  ],
  "tool": [
    { "@type": "HowToTool", "name": "Mixing bowl" },
    { "@type": "HowToTool", "name": "Baking sheet" },
    { "@type": "HowToTool", "name": "Oven" }
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "Preheat oven",
      "text": "Preheat oven to 350°F (175°C)."
    },
    {
      "@type": "HowToStep",
      "name": "Mix ingredients",
      "text": "Mix flour, sugar, and chocolate chips in a bowl."
    },
    {
      "@type": "HowToStep",
      "name": "Bake",
      "text": "Place on baking sheet and bake for 12-15 minutes."
    }
  ]
}

Example 3: Incomplete HowTo Schema

Problematic state:


{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Fix a Leaky Faucet"
}

Missing required step property

Corrected state:


{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Fix a Leaky Faucet",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Turn off water supply",
      "text": "Locate and turn off the water supply valve under the sink."
    },
    {
      "@type": "HowToStep",
      "name": "Disassemble faucet",
      "text": "Remove the handle and disassemble the faucet to access the washer."
    }
  ]
}

Unit Test

Test File

xeopix-crawling-v2/__tests__/seo-audit-checks/structuredDataRichResults/issue-149-howto-schema.test.js

Purpose

Validates that the crawler correctly validates HowTo JSON-LD schemas and does not report false positives when the schema is properly formed.

Tested Function

runStructuredDataRichResults()

Issue Information

Issue Number: 149
Issue Code: howto_schema_instructional
Toggle Group: structuredDataRichResults

Test Scenarios

Positive Test Cases

Valid HowTo schema: Page has a HowTo schema with name and step containing HowToStep entries — no issue reported.

Negative Test Cases

None — the test only validates that valid schemas pass.

Boundary Cases

None.

Edge Cases

Empty HTML: <html></html> — no crash.

Expected Outcome

Pass

Issue should not be reported when a valid HowTo schema with required properties is present.

Fail

No negative test cases are defined.

Validation

Correct pass-through of valid HowTo schemas
Graceful handling of empty HTML

xeopix-crawling-v2/toggleGroups/structuredDataRichResults.js
xeopix-crawling-v2/issueCodes.js
xeopix-crawling-v2/utils/context.js
xeopix-crawling-v2/utils/issues.js
xeopix-crawling-v2/utils/schema.js

Coverage Summary

Covers valid HowTo schema detection
Covers empty HTML resilience

References

Schema.org — HowTo — Schema.org
Google — HowTo Structured Data — Google Search Central