JSON-LD HowTo Schema Builder

HowTo structured data for tutorials

The schema.org HowTo type describes a task that a reader completes through a sequence of steps. Marking up tutorials, recipes-as-instructions, and setup guides with HowTo JSON-LD gives search engines an ordered, machine-readable version of your instructions. This builder turns a simple line-per-step list into a fully nested HowTo schema.

How it works

The output object has @type of HowTo with the task name and an optional totalTime in ISO 8601 duration format. Each line you enter becomes a HowToStep object inside the step array, with text set to the step content and a position index reflecting its order. If a line contains a pipe (|), the text before it becomes the step text and the part after becomes that step’s image. Empty lines are skipped so the step list stays clean and correctly numbered.

Tips and example

Write totalTime as a duration: 45 minutes is PT45M. To attach an image, format a line as Tighten the bolt | https://example.com/bolt.jpg. A generated block looks like this:

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Set up a Node project",
  "totalTime": "PT10M",
  "step": [
    {
      "@type": "HowToStep",
      "position": 1,
      "text": "Run npm init to create package.json"
    },
    {
      "@type": "HowToStep",
      "position": 2,
      "text": "Install dependencies with npm install",
      "image": "https://example.com/install.png"
    }
  ]
}

Keep the on-page instructions identical to the marked-up steps — structured data must reflect visible content, or it risks being treated as spam.

What HowTo schema actually does for you

HowTo markup gives search engines an ordered, machine-readable version of your instructions. Even though Google has reduced direct rich result display for HowTo in standard web search, the markup still serves several useful purposes:

1. AI assistants and voice search. Systems like Google Assistant can read the step array to deliver step-by-step instructions verbally, including the correct sequence. A well-marked-up tutorial is more likely to be surfaced than an unmarked page when someone asks “how do I install Node.js” through a voice interface.
2. Bing and other engines. Bing continues to surface HowTo rich results in its own search features and in Copilot-powered answers.
3. Future eligibility. The markup is on your page and does no harm. When search features change, pages with valid schema are already eligible without requiring a re-crawl or re-submission.

Getting the totalTime format right

ISO 8601 durations look unusual if you have not seen them before. The format is PT followed by hours (H), minutes (M), and seconds (S):

Omit totalTime entirely rather than guessing — it is optional, and an inaccurate time is worse than none.

Step images and when to use them

Each HowToStep can optionally include an image property pointing to a visual that illustrates that specific step. These images are most useful for physical tasks (assembling furniture, cooking, hardware setup) where a picture genuinely aids understanding. For purely code-based or text-based instructions, step images add markup complexity without meaningful benefit.

To add an image in this builder, append a pipe (|) after the step text followed by the full image URL:

Tighten the four screws | https://example.com/images/step3-screws.jpg

The image URL must be publicly accessible over HTTPS and should show the state of the task after the step is completed, not before.

Keeping markup and content in sync

One critical requirement: the steps in your JSON-LD must match the steps visible on the page. Google cross-references the markup against the visible content, and significant divergence can trigger a manual action for misleading structured data. If you update your instructions — adding a new prerequisite step, combining two steps into one — update the schema at the same time.