From 901763851279fdb368a11f9fcf9dc6930ef387bf Mon Sep 17 00:00:00 2001
From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com>
Date: Wed, 5 Aug 2026 07:10:08 +0000
Subject: [PATCH] docs(schema-aggregator): document new schemamap.xml site-root
 URL

Yoast SEO 28.3-RC2 adds a new rewrite-based URL at the site root
(`schemamap.xml`) that serves the same XML as the existing REST endpoint.
---
 .../schema/schema-aggregator/api-reference.md | 54 ++++++++++++++++++-
 .../schema/schema-aggregator/overview.md      | 29 ++++++----
 2 files changed, 72 insertions(+), 11 deletions(-)

diff --git a/docs/features/schema/schema-aggregator/api-reference.md b/docs/features/schema/schema-aggregator/api-reference.md
index e5b0d3b8..c257798a 100644
--- a/docs/features/schema/schema-aggregator/api-reference.md
+++ b/docs/features/schema/schema-aggregator/api-reference.md
@@ -78,9 +78,59 @@ curl https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/post/2
 
 ---
 
-### Get XML Schemamap
+### Get XML Schemamap — site-root URL (since 28.3)
 
-Retrieve an XML sitemap of all available schema endpoints.
+Starting with Yoast SEO 28.3, the schemamap is also served at the site root as a plain XML file:
+
+```
+GET https://example.com/schemamap.xml
+```
+
+This URL is served by WordPress's rewrite layer (no REST API required) and returns the same XML document as the REST endpoint below. AI crawlers and NLWeb-compliant consumers can fetch it without knowing the WordPress REST API path prefix.
+
+**Response Format:**
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+   <url contentType="structuredData/schema.org">
+      <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/page</loc>
+      <lastmod>2026-01-01T14:03:56Z</lastmod>
+      <changefreq>daily</changefreq>
+      <priority>0.8</priority>
+   </url>
+   <url contentType="structuredData/schema.org">
+      <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/post</loc>
+      <lastmod>2026-01-01T14:03:56Z</lastmod>
+      <changefreq>daily</changefreq>
+      <priority>0.8</priority>
+   </url>
+</urlset>
+```
+
+**Response Headers:**
+
+```
+Content-Type: application/xml; charset=UTF-8
+Cache-Control: public, max-age=300
+X-Robots-Tag: noindex, follow
+```
+
+**Example Request:**
+
+```bash
+curl https://example.com/schemamap.xml
+```
+
+:::note
+The site-root URL and the REST endpoint both serve the same cached XML. Yoast SEO automatically flushes the cache when relevant content changes, so both URLs stay in sync.
+:::
+
+---
+
+### Get XML Schemamap — REST endpoint
+
+Retrieve an XML sitemap of all available schema endpoints via the REST API.
 
 **Endpoint:**
 ```
diff --git a/docs/features/schema/schema-aggregator/overview.md b/docs/features/schema/schema-aggregator/overview.md
index 494b948a..15af61f2 100644
--- a/docs/features/schema/schema-aggregator/overview.md
+++ b/docs/features/schema/schema-aggregator/overview.md
@@ -66,18 +66,29 @@ The Schema Aggregator implements a dynamic caching strategy:
 
 ### Schemamap (XML map for structured data)
 
-The schemamap provides an XML index of all available schema endpoints:
+The schemamap provides an XML index of all available schema endpoints. Starting with Yoast SEO 28.3, the schemamap is accessible at two URLs:
+
+- **Site-root URL** (new in 28.3): `https://example.com/schemamap.xml` — a plain URL served by WordPress's rewrite layer, designed for AI crawlers and NLWeb-compliant consumers.
+- **REST endpoint**: `https://example.com/wp-json/yoast/v1/schema-aggregator/get-xml` — the original REST API path.
+
+Both URLs return the same cached XML document:
 
 ```xml
 <?xml version="1.0" encoding="UTF-8"?>
-<schemalist>
-    <schema>
-        <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/post</loc>
-    </schema>
-    <schema>
-        <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/page</loc>
-    </schema>
-</schemalist>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+   <url contentType="structuredData/schema.org">
+      <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/post</loc>
+      <lastmod>2026-01-01T14:03:56Z</lastmod>
+      <changefreq>daily</changefreq>
+      <priority>0.8</priority>
+   </url>
+   <url contentType="structuredData/schema.org">
+      <loc>https://example.com/wp-json/yoast/v1/schema-aggregator/get-schema/page</loc>
+      <lastmod>2026-01-01T14:03:56Z</lastmod>
+      <changefreq>daily</changefreq>
+      <priority>0.8</priority>
+   </url>
+</urlset>
 ```
 
 ### External source support