WebMEM™

The Protocol for Structuring, Delivering, and Conditioning Trust-Scored AI Memory on the Open Web

WebMEM SemanticMap

WebMEM SemanticMap (WM-SM) Specification

Part of the WebMEM Protocol
Location: /specification/semanticmap/
Status: v1.0 (Draft)
Namespaces (URNs):
urn:webmem:trustmap:1.0 (TM-CORE sitemap binding) ·
urn:webmem:semanticmap:1.0 (optional extension binding)
Last Updated: 2025-09-09

Contents

  1. SemanticMap Overview
  2. Relationship to SDT (YAML-in-HTML)
  3. Profiles & Conformance
  4. Fragment Model (MapFragment)
  5. TM-CORE (Sitemap Binding)
  6. SM-EXT (Semantic Extensions)
  7. Enumerations
  8. Minimal Example (TM-CORE)
  9. Full Example (TM-CORE + SM-EXT)
  10. Producer Rules
  11. Consumer Rules
  12. Validation & XSD Stubs
  13. Future Bindings (RDF/JSON)
  14. Changelog

1) SemanticMap Overview

WebMEM SemanticMap (WM-SM) defines a navigation-layer fragment carried in XML sitemaps to condition agent retrieval. A MapFragment attaches trust, provenance, fragment identity, and optional semantic hints to a URL so agents can pre-triage before fetching.

WM-SM consists of:

• TM-CORE — the backwards-compatible sitemap binding (a.k.a. “TrustMap”) using urn:webmem:trustmap:1.0.

• SM-EXT — optional semantic extensions (intent, audience, validity, scope hints, lineage, etc.).

2) Relationship to SDT (YAML-in-HTML)

SDT defines page-layer fragments (e.g., DataFragment) embedded via YAML-in-HTML. WM-SM defines navigation-layer fragments in sitemaps. Both layers align by sharing:

• fragment (stable ID like plan:H5521-290-0)

• scope (e.g., landscape, performance, pbp)

• digest (dataset/digest token)

This alignment enables cross-fragment retrieval and citation.

3) Profiles & Conformance

TM-CORE (required for compliance):

signal, confidence, entityType, fragment, scope, provenance, digest inside a sitemap MapFragment.

SM-EXT (optional):

relatedFragments, agentHint, glossaryRef, validity, intent, audience, scopeHint, lineage, source, checksum, endpoints, meta.

SM-FULL: TM-CORE + SM-EXT.

4) Fragment Model (MapFragment)

MapFragment = the semantic payload attached to a URL in a sitemap. In the TM-CORE binding it is represented by <wm:trust> (container) and its child elements.

urlset
 └─ url
    ├─ loc, lastmod, changefreq, priority   (standard)
    └─ wm:trust (MapFragment; optional, ≤1 per <url>)
       ├─ CORE fields     (required by TM-CORE)
       └─ EXT fields      (optional; SM-EXT)

5) TM-CORE (Sitemap Binding)

Namespace (URN): xmlns:wm="urn:webmem:trustmap:1.0"
Container: <wm:trust wm:version="1.0">

Required fields (order SHOULD be preserved):

  • <wm:signal> — enum: very-high | high | medium | low
  • <wm:confidence> — decimal 0.00–1.00 (two decimals). Publisher-declared provenance strength (truth weight), not crawl priority.
  • <wm:entityType> — enum: plan | county | state | provider | formulary | contract | glossary
  • <wm:fragment> — string entityType:ID (e.g., plan:H5521-290-0)
  • <wm:scope> — enum: landscape | performance | pbp | enrollment | metadata
  • <wm:provenance> — dataset token (e.g., 2025-cms-landscape)
  • <wm:digest> — digest token (e.g., 2025-cms-ma-mapd-plan)

Constraints (MUST):

  • At most one MapFragment (wm:trust) per <url>.
  • wm:fragment prefix MUST match wm:entityType.
  • wm:confidence MUST NOT be derived from sitemap priority.
  • Enums are lowercase, hyphenated.

6) SM-EXT (Semantic Extensions)

Extensions MAY be included within the MapFragment. They are optional and advisory.

  • <wm:relatedFragments> container
    • child <wm:fragment ref="" scope="" digest="" type="overlay|extension|replacement" />
  • <wm:agentHint> — heuristic, e.g., prefer:landscape; fallback:performance
  • <wm:glossaryRef> — URL to canonical glossary page
  • <wm:meta> — container for small semantic hints:
    • <wm:intent> — inform | compare | recommend | warn
    • <wm:audience> — consumer | provider | regulator | researcher
    • <wm:validity from="" to="" asOf=""/> — ISO-8601 dates
    • <wm:scopeHint> — national | state | county | zip
    • <wm:supersedes> / <wm:supersededBy> — lineage tokens or URLs
  • <wm:source> — dataset URI/token (e.g., cms:landscape:2025)
  • <wm:checksum alg="sha256|sha384|sha512">HEX</wm:checksum> — integrity hint
  • <wm:endpoints> with children <wm:endpoint rel="" href=""/> (e.g., jsonld, ttl)

7) Enumerations

  • signal: very-high | high | medium | low
  • entityType: plan | county | state | provider | formulary | contract | glossary
  • scope: landscape | performance | pbp | enrollment | metadata
  • type (related fragment): overlay | extension | replacement
  • intent: inform | compare | recommend | warn
  • audience: consumer | provider | regulator | researcher
  • scopeHint: national | state | county | zip

8) Minimal Example (TM-CORE)

<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:wm="urn:webmem:trustmap:1.0">
  <url>
    <loc>https://example.com/plans/H0000-000-0/</loc>
    <lastmod>2025-09-09</lastmod>
    <priority>0.90</priority>
    <!-- wm:trust metadata is for agentic retrieval systems. Safe to ignore for traditional crawlers. -->
    <wm:trust wm:version="1.0">
      <wm:signal>very-high</wm:signal>
      <wm:confidence>1.00</wm:confidence>
      <wm:entityType>plan</wm:entityType>
      <wm:fragment>plan:H0000-000-0</wm:fragment>
      <wm:scope>landscape</wm:scope>
      <wm:provenance>2025-cms-landscape</wm:provenance>
      <wm:digest>2025-cms-ma-mapd-plan</wm:digest>
    </wm:trust>
  </url>
</urlset>

9) Full Example (TM-CORE + SM-EXT)

<url>
  <loc>https://medicarewire.com/medicare-advantage/plans/H5521-290-0/</loc>
  <lastmod>2025-09-09</lastmod>
  <changefreq>monthly</changefreq>
  <priority>0.98</priority>
  <!-- wm:trust metadata is for agentic retrieval systems. Safe to ignore for traditional crawlers. -->
  <wm:trust wm:version="1.0">
    <wm:signal>very-high</wm:signal>
    <wm:confidence>1.00</wm:confidence>
    <wm:entityType>plan</wm:entityType>
    <wm:fragment>plan:H5521-290-0</wm:fragment>
    <wm:scope>landscape</wm:scope>
    <wm:provenance>2025-cms-landscape</wm:provenance>
    <wm:digest>2025-cms-ma-mapd-plan</wm:digest>

    <wm:relatedFragments>
      <wm:fragment ref="plan:H5521-290-0" scope="performance"
                   digest="2025-cms-part-c-and-d-performance" type="extension"/>
      <wm:fragment ref="plan:H5521-290-0" scope="pbp"
                   digest="2025-cms-pbp" type="overlay"/>
    </wm:relatedFragments>

    <wm:agentHint>prefer:landscape; fallback:performance</wm:agentHint>
    <wm:glossaryRef>https://memoryfirst.org/glossary/performanceMetrics</wm:glossaryRef>

    <wm:meta>
      <wm:intent>inform</wm:intent>
      <wm:audience>consumer</wm:audience>
      <wm:validity from="2025-01-01" to="2025-12-31" asOf="2025-09-01"/>
      <wm:scopeHint>county</wm:scopeHint>
      <!-- <wm:supersedes>plan:H5521-290-0@2024</wm:supersedes> -->
      <!-- <wm:supersededBy>plan:H5521-290-0@2026</wm:supersededBy> -->
    </wm:meta>

    <!-- Optional: endpoints, checksum -->
    <!--
    <wm:endpoints>
      <wm:endpoint rel="jsonld" href="https://medicarewire.com/api/plan/H5521-290-0.jsonld"/>
      <wm:endpoint rel="ttl"    href="https://medicarewire.com/api/plan/H5521-290-0.ttl"/>
    </wm:endpoints>
    <wm:checksum alg="sha256">…HEX…</wm:checksum>
    -->

  </wm:trust>
</url>

10) Producer Rules

  • MUST include ≤1 MapFragment (wm:trust) per <url>.
  • MUST populate all TM-CORE fields and maintain formats/enums.
  • MUST ensure confidence reflects provenance (e.g., CMS facts = 1.00).
  • SHOULD keep field order stable; use lowercase, hyphenated enums.
  • MAY add the advisory comment above wm:trust.

11) Consumer Rules

  • MUST ignore unknown fields gracefully.
  • MAY use entityType/fragment/scope/digest for pre-fetch triage.
  • MAY weight retrieval with signal and confidence.
  • SHOULD treat agentHint as advisory only.

12) Validation & XSD Stubs

TM-CORE simple types (stub):

<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
            targetNamespace="urn:webmem:trustmap:1.0"
            xmlns:wm="urn:webmem:trustmap:1.0"
            elementFormDefault="qualified">

  <xsd:simpleType name="Signal">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="very-high"/>
      <xsd:enumeration value="high"/>
      <xsd:enumeration value="medium"/>
      <xsd:enumeration value="low"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="Scope">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="landscape"/>
      <xsd:enumeration value="performance"/>
      <xsd:enumeration value="pbp"/>
      <xsd:enumeration value="enrollment"/>
      <xsd:enumeration value="metadata"/>
    </xsd:restriction>
  </xsd:simpleType>

  <xsd:simpleType name="EntityType">
    <xsd:restriction base="xsd:string">
      <xsd:enumeration value="plan"/>
      <xsd:enumeration value="county"/>
      <xsd:enumeration value="state"/>
      <xsd:enumeration value="provider"/>
      <xsd:enumeration value="formulary"/>
      <xsd:enumeration value="contract"/>
      <xsd:enumeration value="glossary"/>
    </xsd:restriction>
  </xsd:simpleType>

  <!-- Extend with complexTypes for wm:trust, wm:relatedFragments, wm:meta as spec matures -->
</xsd:schema>

13) Future Bindings (RDF/JSON)

WM-SM may define RDF (TTL/JSON-LD) or JSON feed bindings that mirror TM-CORE/SM-EXT fields for non-sitemap transports. These MUST preserve fragment, scope, and digest semantics.

14) Changelog

  • 1.0 (2025-09-09): Initial SemanticMap spec (TM-CORE sitemap binding + SM-EXT options).