The naive version of this tool is one prompt: "Here is a URL, write the JSON-LD for it." We tried that mental model early and threw it out. An LLM handed a bare URL will produce schema that looks perfect and is quietly wrong. It guesses an author when the page has none. It invents a publication date. On a commerce page it will cheerfully write a price that appears nowhere in the markup. The output validates, parses, and ships, and then an AI engine reads a fabricated author name as a confirmed fact. For a tool you paste straight into production, that is the worst possible failure, because it is invisible until something downstream cites the lie.

So we built the pipeline backwards from that risk. The model never sees a raw URL and never decides what the facts are. By the time Gemini runs, the page has already been read, the facts have already been extracted, and the page type has already been decided by deterministic code. The model's job is narrow: take known facts and a known shape, and emit well-formed JSON-LD. Everything that could be hallucinated is settled before the model is allowed to write a word.

Signal extraction: read the page first

Step one is fetching the page and pulling structured signals out of the DOM. No model here, just parsing. We extract a fixed set of things:

• title, meta description, canonical URL: the page's own identity claims.
• headings, up to 30: the outline, capped so a pathological page cannot blow up the payload.
• images, up to 10: src and alt for each, since alt text is the only image content a schema block can carry.
• author: searched across three selector families, namely rel="author", the .author and .byline classes, and itemprop="author".
• publication date: read from <time> elements and the article:published_time meta tag.
• breadcrumbs: from a nav ol or any breadcrumb-named class.
• price markers: price-related classes and properties, the signal that a page is selling something.
• FAQ markers: faq and accordion classes, plus headings phrased as questions.

The output of this stage is a plain signal bundle. For a photography tutorial it might look like this:

{
  "title": "Shooting in Manual Mode: A Beginner's Walkthrough",
  "metaDescription": "Learn aperture, shutter, and ISO in three steps.",
  "canonical": "https://example.com/blog/manual-mode-walkthrough",
  "headings": ["Step 1: Set your aperture", "Step 2: Pick a shutter speed", "Step 3: Dial in ISO"],
  "images": [{ "src": "/img/aperture.jpg", "alt": "Aperture ring on a lens" }],
  "author": "Dana Okoye",
  "publishedTime": "2026-04-22",
  "breadcrumbs": ["Home", "Blog", "Photography"],
  "priceMarkers": false,
  "faqMarkers": false
}

Notice what this bundle is: facts, not interpretation. Either author is a string we found in the DOM or it is null. We never fill it. That null is what protects the downstream steps from inventing one.

Heuristics before the LLM

With the signals in hand, we decide the page type ourselves, in plain code, before any model call. It runs as an ordered ladder and stops at the first match:

• price markers present → product
• FAQ markers present → faq
• author present and date present → blog_post
• title contains "about" or "team" → organization
• title contains "contact" → local_business
• two or more "Step N" headings → how_to
• otherwise → generic

Order matters because the conditions overlap. A product page can also have an author and a date; checking price first means it resolves to product rather than getting misclassified as a blog post three rungs down. The ladder reads top to bottom and the first hit wins.

Three reasons this happens before the model, not inside it:

1. Deterministic grounding. When the model is told "this is a how_to," it writes schema for a known shape. It is not guessing the shape and the content in the same breath. Splitting "what kind of page is this" from "fill in the fields" removes the highest-variance decision from the part of the system that can hallucinate.
2. Cheaper calls. A rule that reads a boolean is free. Spending an LLM call to classify a page you can classify with a string match is waste at scale.
3. A constrained LLM job. The smaller the question we hand the model, the more reliable its answer. "Produce a HowTo block from these steps" is a tight prompt. "Figure out what this page is and write schema for it" is an open-ended one, and open-ended is where models drift.

The Gemini step

Now the model runs. Gemini Flash receives the signal bundle plus the detected type, and returns typed JSON-LD: one block per applicable type, each with a confidence score and a short explanation of why that type fit. We run it in JSON mode, so the response is constrained to valid JSON and our parser never has to scrape a code fence out of prose or recover from a stray sentence the model added. Structured output goes in, structured output comes back.

The rule we press hardest in the prompt is on missing facts. The model is instructed that any field it was not handed a value for must be emitted as an explicit, clearly labeled placeholder. It is forbidden to substitute a plausible value of its own. If the signal bundle has author: null, the author field comes back as a placeholder token, never as a name the model decided sounded right. This is the whole safety property of the tool stated as a prompt constraint: a gap stays a visible gap, marked for a human to fill, instead of becoming a confident fabrication that reads as fact. We would rather hand someone a block with three placeholders to complete than one with three invented values to discover later.

Degrading gracefully

The model call can fail. The API times out, refuses the request, or returns something we reject. When that happens, the tool does not show an error page and send the user away empty-handed. It still returns the type detection from the heuristic ladder and template JSON-LD blocks for that type, with the same placeholder structure the model would have produced. You lose the model's per-field confidence scoring and its explanation, and you keep a correctly typed skeleton you can fill in by hand. An empty, well-shaped suggestion beats a 500. The deterministic half of the pipeline carries the result on its own when the probabilistic half is unavailable.

What comes out

For the photography tutorial above, with the type resolved to how_to and an author present, the generated block looks like this, abbreviated:

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Shooting in Manual Mode: A Beginner's Walkthrough",
  "step": [
    { "@type": "HowToStep", "name": "Set your aperture", "text": "PLACEHOLDER_STEP_DETAIL" },
    { "@type": "HowToStep", "name": "Pick a shutter speed", "text": "PLACEHOLDER_STEP_DETAIL" },
    { "@type": "HowToStep", "name": "Dial in ISO", "text": "PLACEHOLDER_STEP_DETAIL" }
  ],
  "author": { "@type": "Person", "name": "Dana Okoye" }
}

The step names came off the headings, the author came off the DOM, and the per-step detail text the page did not expose cleanly is left as a visible placeholder. Nothing in that block is a value the model wished into existence.

One caveat before you dismiss the HowTo type: Google retired HowTo rich results in 2023, so this markup earns no badge in the SERP anymore. We keep emitting it anyway, because the GEO use is different. The block still hands an AI engine an ordered procedure it can reproduce faithfully, step for step, without reconstructing the sequence from prose. That is the point here, not chasing a rich-result enhancement that no longer exists. The full output ships as a ready-to-paste <script type="application/ld+json"> tag, across the type range the pipeline supports: Article and BlogPosting, Product, FAQPage, LocalBusiness, HowTo, BreadcrumbList, Organization, and WebPage or WebSite.

Try it

The Schema Generator runs this whole pipeline on a URL you give it: extract, classify, generate, score. Then, after you fill the placeholders, run the result through the Schema Validator to confirm your edits did not break the block against schema.org rules.

If you take one idea from how this is built, take the ordering. The instinct with a capable model is to hand it the whole problem and admire what comes back. The better discipline is to figure out which decisions must never be probabilistic, classification and fact-finding here, settle those in code, and let the model do only the bounded part that remains. The pipeline is more reliable not because the model is weaker but because we gave it less room to be wrong.

Mehul Jain is an AI entrepreneur and product builder. He works on Geology, a GEO platform.