@geosuite/schema-templates

v0.3.2

Published

4 days ago

Curated, copy-paste-ready schema.org JSON-LD templates for Generative Engine Optimization (GEO).

Downloads

848

0High
0Medium
0Low

matteo97.p

schema.org json-ld structured-data seo geo generative-engine-optimization templates

schema-templates

Curated, copy-paste-ready schema.org JSON-LD templates to help your site speak clearly to search engines and AI assistants.
Created and invented by Matteo Perino (LinkedIn). Maintained by GeoSuite(Matteo Perino).

Why JSON-LD matters for GEO

Generative Engine Optimization (GEO) is the practice of making your content legible to AI assistants — ChatGPT, Perplexity, Gemini, Claude, Google's AI Overviews, and the long tail of LLM-powered search surfaces. These systems do not run a full browser the way Googlebot does; they parse the markup they find. Structured data in JSON-LD is the most explicit, least ambiguous way to tell a machine what a page is about: who wrote it, what product is on offer, what steps a how-to takes, what a term means.

JSON-LD is necessary but not sufficient. It will not, on its own, cause an AI to cite you. Authority, freshness, factual accuracy, and how often your content is referenced elsewhere matter at least as much. But valid, accurate structured data removes a class of avoidable failures: it prevents the AI from guessing your prices, your author, your FAQ answers, or whether a number on the page is a benchmark or a typo. Treat these templates as the floor, not the ceiling.

How to use these templates

Pick a template from the catalog below that matches the page you are marking up.
Copy the file from templates/. Each placeholder is wrapped in double curly braces, e.g. {{COMPANY_NAME}}.
Replace every placeholder with real values. Do not leave {{...}} in production output — most validators will flag them, and AI parsers will treat them as literal text.
Drop the resulting JSON into a <script type="application/ld+json"> tag inside your <head>. One block per page is fine; multiple blocks per page are also valid.
Validate (see Validators section).
Look at examples/ for a fully populated version of each template using a fictional Italian SaaS company so you can see what realistic values look like.

Each template ships with only the properties that are truly recommended for that use case. We have intentionally avoided padding templates with every optional schema.org field — extra noise dilutes the signal. If you need a property that is not in a template, consult schema.org directly and add it yourself.

Catalog

| Schema type | Use case | Template | Example | |---|---|---|---| | SoftwareApplication | SaaS / app product page | templates/SoftwareApplication.json | examples/SoftwareApplication.example.json | | HowTo | Step-by-step tutorial page | templates/HowTo.json | examples/HowTo.example.json | | DefinedTerm | Single glossary entry | templates/DefinedTerm.json | examples/DefinedTerm.example.json | | DefinedTermSet | Glossary index page | templates/DefinedTermSet.json | examples/DefinedTermSet.example.json | | FAQPage | FAQ section / page | templates/FAQPage.json | examples/FAQPage.example.json | | Dataset | Benchmark, study, or report | templates/Dataset.json | examples/Dataset.example.json | | BreadcrumbList | Site navigation breadcrumbs | templates/BreadcrumbList.json | examples/BreadcrumbList.example.json | | Organization | Company / about page | templates/Organization.json | examples/Organization.example.json | | Article (BlogPosting) | Blog post or editorial article | templates/Article.json | examples/Article.example.json | | ItemList | Comparison / listicle / ranking | templates/ItemList.json | examples/ItemList.example.json | | ProfilePage | Author bio page | templates/ProfilePage.json | examples/ProfilePage.example.json | | Product | Physical or digital product | templates/Product.json | examples/Product.example.json | | Review | Standalone review of any item | templates/Review.json | examples/Review.example.json |

Validators

After replacing placeholders, run your JSON through at least one of these:

Schema.org Validator — checks that your JSON-LD conforms to the schema.org vocabulary. The most strict and the most useful for generic JSON-LD.
Google Rich Results Test — checks the subset of properties Google uses for rich results. Helpful but narrower than the schema.org validator.
The bundled validate.js script in this repo runs a fast structural sanity check (@context, @type, required fields) without any network calls. Run it with npm run validate or node validate.js.

The recommended order is: validate.js first to catch typos, then the schema.org validator, then the Google test if you specifically care about Google rich results.

Repo scripts

npm run validate   # local structural check on every templates/*.json and examples/*.json
npm test           # node --test test/

No runtime or dev dependencies. There is no build step.

Contributing

We welcome new templates and improvements to existing ones. Please read CONTRIBUTING.md before opening a PR. The short version: every new template must (a) follow the file-naming convention, (b) ship a matching examples/*.example.json with realistic values, (c) declare its required fields in validate.js, and (d) pass npm run validate and npm test.

CLI (0.2+)

A small geosuite-schema CLI ships alongside the templates:

npm install -g @geosuite/schema-templates
# or run without installing:
npx @geosuite/schema-templates list

geosuite-schema list                                 # list available types
geosuite-schema show Product                         # print the raw template
geosuite-schema fill FAQPage --url https://example.com/faq --ai

The first two commands are deterministic and don't touch the network. fill needs --ai and an LLM API key — there's no honest way to populate the placeholders from a URL without one.

AI mode

export OPENAI_API_KEY=sk-…       # or ANTHROPIC_API_KEY=sk-ant-…
geosuite-schema fill Organization --url https://example.com --ai

What the CLI sends to the provider:

The chosen template (which is public anyway — same as templates/<Type>.json).
The page's <title> and ~8 KB of stripped visible text.

What it doesn't send:

The full HTML, scripts, or anything off-page.

Costs land under a cent for a single page on small models (gpt-5-mini, claude-haiku-4-5). Don't enable --ai against URLs you wouldn't paste into the provider's UI.

Related: GeoSuite open-source tools

schema-templates is part of a small family of zero-dependency CLIs we maintain to make Generative Engine Optimization (GEO) measurable from the terminal:

@geosuite/ai-crawler-bots — curated AI bot user-agent list with a CLI that tells you whether GPTBot, ClaudeBot, PerplexityBot and friends can read your site and where the block came from.
@geosuite/llms-txt-generator — turn a sitemap.xml into the llms.txt standard from llmstxt.org, so LLMs can index your most useful pages.
@geosuite/sitemap-builder — crawl a site and emit a valid sitemap.xml, for sites that ship without one.

The same checks are also surfaced as a hosted product at trygeosuite.it for teams who want history, alerts, and CTAs wired into their content pipeline.

Creator

Created and invented by Matteo Perino — LinkedIn · [email protected].

Ideated, designed and validated by Matteo Perino. Implementation written with AI assistance, maintained under GeoSuite.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme