Introducing @ranklabs/schema

February 11, 2026 · Sangmin Lee

@ranklabs/schema cover

We open-sourced our structured data toolkit

Today we're releasing @ranklabs/schema — the same Schema.org JSON-LD library we use internally at RankLabs, now available as an open-source package on npm.

If you sell products online or run a SaaS, your structured data is how AI models like ChatGPT, Gemini, and Perplexity understand what you offer. Most sites either skip it entirely or produce fragmented markup that machines can't reliably parse.

We built @ranklabs/schema to fix that.

What it does

The package gives you typed inputs, pure mapper functions, and graph-first JSON-LD composition — everything you need to produce clean, deterministic structured data.

Products — handles simple products, variant groups, offers, reviews, and aggregate ratings
Pages — web pages, articles, FAQs, collection pages, breadcrumbs
Identity — organizations, brands, websites with search actions
SaaS — software application schema for non-physical products
Media — images and videos with proper Schema.org types

Every mapper takes a typed input and returns a Schema.org node. You compose them into a single @graph — one script tag per page, no duplication, no ambiguity.

import { createGraph, mapProduct, mapWebPage, mapOrganization } from '@ranklabs/schema';
 
const jsonLd = createGraph(
  mapProduct(productInput),
  mapWebPage(pageInput),
  mapOrganization(orgInput),
);

That's it. One graph, stable @id references, and every entity defined exactly once.

Why graphs matter

Most structured data implementations scatter multiple <script type="application/ld+json"> blocks across a page. This works for basic use cases, but it breaks down when:

Multiple plugins inject overlapping schema
The same brand or organization is repeated on every page
Products share attributes with parent pages

With a single @graph, entities are defined once and cross-referenced by @id. AI models can resolve relationships explicitly instead of guessing. This is especially important for LLMs, which reason over entity graphs rather than isolated documents.

Built-in validation

Bad structured data is worse than no structured data — it actively causes hallucinations. The package includes opt-in runtime validation:

import { prepareJsonLd } from '@ranklabs/schema';
 
const cleaned = prepareJsonLd(jsonLd, { mode: 'warn' });

prepareJsonLd strips empty fields, validates the structure, and warns you in development if something is off. In production, it silently cleans the output so you never ship broken markup.

Framework adapters

We also released two companion packages for teams that want drop-in React components:

@ranklabs/schema-next — for Next.js (App Router and Pages Router)
@ranklabs/schema-hydrogen — for Shopify Hydrogen storefronts

Both packages provide <JsonLd /> components that handle serialization, HTML escaping, and <script> tag injection for you.

Install

npm i @ranklabs/schema

For framework adapters:

npm i @ranklabs/schema-next     # Next.js
npm i @ranklabs/schema-hydrogen # Shopify Hydrogen

What's inside

Types — ProductInput, WebPageInput, OrganizationInput, ArticleInput, SaaSInput, and more
Mappers — mapProduct, mapWebPage, mapOrganization, mapArticle, mapFAQPage, mapSaaS, etc.
Graph utilities — createGraph, withContext, toJsonLdString, toJsonLdScriptTag
ID helpers — canonicalId.product(), canonicalId.webpage(), canonicalId.organization(), etc.
Validation — cleanJsonLd, validateJsonLd, prepareJsonLd

The full API and cookbooks are on GitHub.

Why we open-sourced it

Structured data is infrastructure. Every e-commerce store and SaaS needs it, but the tooling has been fragmented — scattered blog posts, copy-pasted JSON blobs, and no type safety.

We think the right approach is a single, well-maintained library that produces the cleanest possible output. By open-sourcing it, we hope to raise the baseline for structured data quality across the web — which ultimately makes AI recommendations more accurate for everyone.

If you want to go further — automated schema generation, real-time validation, competitive benchmarking, and AI visibility monitoring — that's what the RankLabs platform does.

Get started

npm: npmjs.com/package/@ranklabs/schema
GitHub: github.com/ranklabsai/ranklabs-schema
Docs: Cookbooks & Guides

We'd love your feedback. Open an issue, submit a PR, or just let us know what you think on X.