NLWeb Schema.org Grounding
Before writing code
Fetch live references:
- Fetch https://schema.org/ for the canonical Schema.org vocabulary.
- Fetch https://github.com/nlweb-ai/NLWeb/blob/main/config/site_types.xml in the live repo for the exact list of supported Schema.org types and the tool inheritance tree per type.
- Fetch https://github.com/nlweb-ai/NLWeb/blob/main/docs/nlweb-prompts.md for how per-type prompts and
<returnStruc> shapes work.
- Web-search
schema.org JSON-LD validator — Google's Rich Results Test is a quick way to validate before ingest.
- Check
AskAgent/python/methods/recipe_substitution.py, accompaniment.py, compare_items.py for examples of how type-specific tools consume the schema_object.
Conceptual Architecture
Why Schema.org Matters to NLWeb
NLWeb's defining design choice: results carry their full Schema.org object back to the agent. Unlike a generic RAG system that returns text chunks, NLWeb returns structured JSON-LD — so an agent receiving a Recipe result gets ingredients, cookTime, nutrition, recipeYield, not just a paragraph of text. This is what makes NLWeb results agent-actionable.
R.V. Guha (NLWeb's author) co-created Schema.org for exactly this reason — the data was already structured; NLWeb finally exposes it to agents.
Schema.org Types NLWeb Knows About
site_types.xml enumerates the types with per-type tool / prompt overrides. Common types (verify the live file):
| Type |
Use Case |
Type-Specific Tools |
Recipe |
Cooking sites |
recipe_substitution, accompaniment |
Product |
E-commerce |
compare_items, item_details |
Movie / TVSeries |
Streaming/reviews |
compare_items |
Event |
Calendars, ticketing |
item_details |
Article / NewsArticle / BlogPosting |
News, blogs |
summarize-mode default |
RealEstate / Apartment / House |
Listings |
item_details, compare |
Course |
EdTech |
item_details |
Restaurant / LocalBusiness |
Maps, directories |
accompaniment, item_details |
Book |
Catalogs |
compare, item_details |
Person / Organization |
Profiles |
item_details |
NLWeb falls back to a default tool set for any Schema.org type not explicitly enumerated.
JSON-LD Embedding Patterns
Schema.org JSON-LD is typically embedded in HTML via a <script type="application/ld+json"> tag:
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "Recipe",
"name": "Classic Tomato Soup",
"url": "https://example.com/recipes/tomato-soup",
"image": "https://example.com/images/tomato-soup.jpg",
"author": { "@type": "Person", "name": "Jane Doe" },
"datePublished": "2025-09-12",
"description": "A simple weeknight tomato soup.",
"recipeIngredient": ["6 ripe tomatoes", "1 onion", "..."],
"recipeInstructions": [...],
"nutrition": { "@type": "NutritionInformation", "calories": "200" },
"cookTime": "PT30M",
"recipeYield": "4 servings"
}
</script>
NLWeb's URL-list ingest path extracts this directly. The richer the JSON-LD, the more useful the result.
The schema_object Field in Responses
Every NLWeb result contains:
{
"url": "...",
"name": "...",
"site": "...",
"score": 0.87,
"description": "...",
"schema_object": { /* the full JSON-LD as ingested */ }
}
Agents can pattern-match on schema_object.@type to render appropriately, extract specific properties (e.g., offers.price for products), or chain to a follow-up tool call.
sites.xml and Per-Site Registration
In addition to config_nlweb.yaml's sites: allowlist, the demo data ships with a sites.xml-style registry tying site names to crawl sources and Schema.org type defaults. Check the live repo for the current registration convention — this is an area that's been evolving.
Schema.org Required Fields by Type (high-signal subset)
| Type |
Always include |
| Recipe |
name, url, image, recipeIngredient, recipeInstructions, cookTime, recipeYield |
| Product |
name, url, image, description, offers (price, priceCurrency, availability) |
| Article |
headline, url, image, author, datePublished, description, articleBody (or summary) |
| Event |
name, url, startDate, location, description |
| Movie |
name, url, image, director, datePublished, genre, description |
| RealEstate |
name, url, image, address, numberOfRooms, floorSize, price |
The fewer fields populated, the worse the result quality — especially for mode=generate answers.
Per-Type Prompt and Tool Inheritance
site_types.xml defines a tree:
- Root prompts apply to all types
- Per-type overrides specialize ranking, summarization, and tool selection
This is mixed-mode programming in action — small, type-aware LLM calls drive the response.
Implementation Guidance
Auditing an Existing Site
Before ingest:
- Visit a representative page and view source — look for
<script type="application/ld+json">.
- Validate with Google's Rich Results Test or Schema.org validator.
- Confirm the
@type is one NLWeb's site_types.xml knows about — if not, results still work but use default prompts.
Authoring JSON-LD for NLWeb
- Always set
@context: "https://schema.org" — NLWeb's parser keys off this.
- Always include
url — it's the deduplication key across retrieval backends.
- Use specific subtypes (e.g.,
Recipe not CreativeWork) so type-specific tools activate.
- Embed images and dates — agents use them for rendering and freshness checks.
- Nest related objects with
@type discriminators (e.g., author as Person, offers as Offer).
Validating Schema Quality Post-Ingest
After loading, hit a result and inspect schema_object:
curl 'http://localhost:8000/ask?query=quick+dinners&site=recipes&streaming=false&mode=list' | jq '.results[0].schema_object'
If schema_object is missing key fields, fix the source HTML — not NLWeb's config.
Adding a New Schema.org Type
If you want a custom domain (say, Podcast episodes) with type-specific tools:
- Add a
<site_type> entry in site_types.xml referencing your @type value.
- Define type-specific prompts in
prompts.xml (or inherit defaults).
- Optionally write a handler in
methods/ (see nlweb-tools-framework).
- Reload and re-test.
Mapping Non-Schema.org Sources
If your source isn't JSON-LD (CSV, proprietary API), map fields to Schema.org at ingest time, not query time. Update rss2schema.py or write a small adapter that emits Schema.org JSON before calling db_load. The richer the mapping, the better the agent experience.
Common Pitfalls
@type is missing or non-Schema.org — results work but type-specific tools never fire.
url is relative — breaks deduplication; always emit absolute URLs.
- Date format is non-ISO —
datePublished: "2025-09-12" works; "Sept 12, 2025" does not.
offers is a bare string instead of an Offer object — agents lose the price field.
- Description is too short / too generic — ranking suffers because retrieval relies on description embeddings.
Always validate JSON-LD with an external tool before assuming ingest will work — silent parser failures are common.
1---2name: nlweb-schema-org-grounding3description: Prepare and structure site content as Schema.org JSON-LD for NLWeb ingestion — covers the supported types (Recipe, Product, Movie, Event, Article, RealEstate, Course, etc.), per-type behavior in NLWeb's tool routing, JSON-LD embedding patterns in HTML, sites.xml registration, and how the `schema_object` flows through ranking back to agent results. Use when authoring or auditing the structured data on a site that will be exposed via NLWeb.4allowed-tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch5metadata:6 source: https://skillmd.com/skills/orcaqubits/nlweb-schema-org-grounding7---89# NLWeb Schema.org Grounding1011## Before writing code1213**Fetch live references**:141. Fetch https://schema.org/ for the canonical Schema.org vocabulary.152. Fetch https://github.com/nlweb-ai/NLWeb/blob/main/config/site_types.xml in the live repo for the **exact list of supported Schema.org types** and the tool inheritance tree per type.163. Fetch https://github.com/nlweb-ai/NLWeb/blob/main/docs/nlweb-prompts.md for how per-type prompts and `<returnStruc>` shapes work.174. Web-search `schema.org JSON-LD validator` — Google's Rich Results Test is a quick way to validate before ingest.185. Check `AskAgent/python/methods/recipe_substitution.py`, `accompaniment.py`, `compare_items.py` for examples of how type-specific tools consume the `schema_object`.1920## Conceptual Architecture2122### Why Schema.org Matters to NLWeb2324NLWeb's defining design choice: **results carry their full Schema.org object back to the agent**. Unlike a generic RAG system that returns text chunks, NLWeb returns structured JSON-LD — so an agent receiving a `Recipe` result gets `ingredients`, `cookTime`, `nutrition`, `recipeYield`, not just a paragraph of text. This is what makes NLWeb results *agent-actionable*.2526R.V. Guha (NLWeb's author) co-created Schema.org for exactly this reason — the data was already structured; NLWeb finally exposes it to agents.2728### Schema.org Types NLWeb Knows About2930`site_types.xml` enumerates the types with per-type tool / prompt overrides. Common types (verify the live file):3132| Type | Use Case | Type-Specific Tools |33|------|----------|---------------------|34| `Recipe` | Cooking sites | recipe_substitution, accompaniment |35| `Product` | E-commerce | compare_items, item_details |36| `Movie` / `TVSeries` | Streaming/reviews | compare_items |37| `Event` | Calendars, ticketing | item_details |38| `Article` / `NewsArticle` / `BlogPosting` | News, blogs | summarize-mode default |39| `RealEstate` / `Apartment` / `House` | Listings | item_details, compare |40| `Course` | EdTech | item_details |41| `Restaurant` / `LocalBusiness` | Maps, directories | accompaniment, item_details |42| `Book` | Catalogs | compare, item_details |43| `Person` / `Organization` | Profiles | item_details |4445NLWeb falls back to a default tool set for any Schema.org type not explicitly enumerated.4647### JSON-LD Embedding Patterns4849Schema.org JSON-LD is typically embedded in HTML via a `<script type="application/ld+json">` tag:5051```html52<script type="application/ld+json">53{54 "@context": "https://schema.org",55 "@type": "Recipe",56 "name": "Classic Tomato Soup",57 "url": "https://example.com/recipes/tomato-soup",58 "image": "https://example.com/images/tomato-soup.jpg",59 "author": { "@type": "Person", "name": "Jane Doe" },60 "datePublished": "2025-09-12",61 "description": "A simple weeknight tomato soup.",62 "recipeIngredient": ["6 ripe tomatoes", "1 onion", "..."],63 "recipeInstructions": [...],64 "nutrition": { "@type": "NutritionInformation", "calories": "200" },65 "cookTime": "PT30M",66 "recipeYield": "4 servings"67}68</script>69```7071NLWeb's URL-list ingest path extracts this directly. The richer the JSON-LD, the more useful the result.7273### The `schema_object` Field in Responses7475Every NLWeb result contains:7677```json78{79 "url": "...",80 "name": "...",81 "site": "...",82 "score": 0.87,83 "description": "...",84 "schema_object": { /* the full JSON-LD as ingested */ }85}86```8788Agents can pattern-match on `schema_object.@type` to render appropriately, extract specific properties (e.g., `offers.price` for products), or chain to a follow-up tool call.8990### sites.xml and Per-Site Registration9192In addition to `config_nlweb.yaml`'s `sites:` allowlist, the demo data ships with a `sites.xml`-style registry tying site names to crawl sources and Schema.org type defaults. Check the live repo for the current registration convention — this is an area that's been evolving.9394### Schema.org Required Fields by Type (high-signal subset)9596| Type | Always include |97|------|----------------|98| Recipe | name, url, image, recipeIngredient, recipeInstructions, cookTime, recipeYield |99| Product | name, url, image, description, offers (price, priceCurrency, availability) |100| Article | headline, url, image, author, datePublished, description, articleBody (or summary) |101| Event | name, url, startDate, location, description |102| Movie | name, url, image, director, datePublished, genre, description |103| RealEstate | name, url, image, address, numberOfRooms, floorSize, price |104105The fewer fields populated, the worse the result quality — especially for `mode=generate` answers.106107### Per-Type Prompt and Tool Inheritance108109`site_types.xml` defines a tree:110- Root prompts apply to all types111- Per-type overrides specialize ranking, summarization, and tool selection112113This is **mixed-mode programming** in action — small, type-aware LLM calls drive the response.114115## Implementation Guidance116117### Auditing an Existing Site118119Before ingest:1201. Visit a representative page and view source — look for `<script type="application/ld+json">`.1212. Validate with Google's Rich Results Test or Schema.org validator.1223. Confirm the `@type` is one NLWeb's `site_types.xml` knows about — if not, results still work but use default prompts.123124### Authoring JSON-LD for NLWeb125126- **Always set `@context: "https://schema.org"`** — NLWeb's parser keys off this.127- **Always include `url`** — it's the deduplication key across retrieval backends.128- **Use specific subtypes** (e.g., `Recipe` not `CreativeWork`) so type-specific tools activate.129- **Embed images and dates** — agents use them for rendering and freshness checks.130- **Nest related objects** with `@type` discriminators (e.g., `author` as `Person`, `offers` as `Offer`).131132### Validating Schema Quality Post-Ingest133134After loading, hit a result and inspect `schema_object`:135136```bash137curl 'http://localhost:8000/ask?query=quick+dinners&site=recipes&streaming=false&mode=list' | jq '.results[0].schema_object'138```139140If `schema_object` is missing key fields, fix the source HTML — not NLWeb's config.141142### Adding a New Schema.org Type143144If you want a custom domain (say, `Podcast` episodes) with type-specific tools:1451. Add a `<site_type>` entry in `site_types.xml` referencing your `@type` value.1462. Define type-specific prompts in `prompts.xml` (or inherit defaults).1473. Optionally write a handler in `methods/` (see `nlweb-tools-framework`).1484. Reload and re-test.149150### Mapping Non-Schema.org Sources151152If your source isn't JSON-LD (CSV, proprietary API), map fields to Schema.org **at ingest time**, not query time. Update `rss2schema.py` or write a small adapter that emits Schema.org JSON before calling `db_load`. The richer the mapping, the better the agent experience.153154### Common Pitfalls155156- **`@type` is missing or non-Schema.org** — results work but type-specific tools never fire.157- **`url` is relative** — breaks deduplication; always emit absolute URLs.158- **Date format is non-ISO** — `datePublished: "2025-09-12"` works; `"Sept 12, 2025"` does not.159- **`offers` is a bare string instead of an `Offer` object** — agents lose the price field.160- **Description is too short / too generic** — ranking suffers because retrieval relies on description embeddings.161162Always validate JSON-LD with an external tool before assuming ingest will work — silent parser failures are common.