WebMEM MapPointer

WebMEM MapPointer (WM-MP) Specification

Part of the WebMEM Protocol
Location: /specification/mappointer/
Status: v1.0 (Draft)
Namespaces (URNs):
urn:webmem:mappointer:1.0 (core pointer binding)
Last Updated: 2025-09-28

MapPointer Overview
Relationship to SDT (YAML-in-HTML)
Profiles & Conformance
Pointer Model (YamlFragmentPointer)
Aggregates & Primitives
Canonicalization & Integrity
Minimal Example (JSON-LD Map)
Full Example (MapPointer + PlanIndex)
Producer Rules
Consumer Rules
Future Extensions
Changelog

1) MapPointer Overview

WebMEM MapPointer (WM-MP) defines the handshake between a lightweight JSON-LD semantic map and a heavy YAML fragment payload. It introduces the YamlFragmentPointer, a stable pointer object with deterministic extraction and cache validation semantics.

WM-MP consists of:

• Pointer Binding — required fields for locating YAML payloads in-page (fragmentId, cssSelector, contentType).

• Integrity Binding — optional but recommended fields (sha256, datePublished, dateModified) for cache and trust.

• Retrieval Primitives — advisory fields (planIDList, topEnrolledPlans, navigationTemplate) for agent fan-out and prefetch.

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

SDT defines page-layer fragments (e.g., DataFragment) published via YAML-in-HTML. WM-MP defines head-layer maps (JSON-LD) that point to those fragments. Together they provide:

• Map (JSON-LD head block) = low-cost discovery, trust anchors, aggregates.

• Payload (YAML body fragment) = canonical fact store, verifiable by hash.

This alignment lets agents parse only the map for fast answers or follow the pointer to fetch granular facts.

3) Profiles & Conformance

MP-CORE (required for compliance):

fragmentId, cssSelector, contentType.

MP-INT (integrity binding, optional):

sha256, datePublished, dateModified.

MP-FULL: MP-CORE + MP-INT + retrieval primitives.

4) Pointer Model (YamlFragmentPointer)

YamlFragmentPointer = the core object linking JSON-LD map to YAML payload.

{
  "@type": "wm:YamlFragmentPointer",
  "fragmentId": "county:az-yavapai-049-landscape-stats",
  "cssSelector": "pre#fragment-az-yavapai-049-landscape-stats",
  "contentType": "application/x-webmem+yaml",
  "sha256": "948bf9f6...",
  "dateModified": "2025-09-20"
}

5) Aggregates & Primitives

Maps may carry light aggregates for fast retrieval (wm:planCount, wm:averageMoop), plus retrieval primitives:

wm:planIDList — array of plan IDs (tokens for agent fan-out)
wm:topEnrolledPlans — enriched objects (identifier, name, enrollmentCount)
wm:navigationTemplate — exact URL grammar for synthesizing plan links

6) Canonicalization & Integrity

WM-MP defines canonicalization rules to ensure reproducible hashing:

Remove BOM if present
Normalize Unicode to NFC
Normalize CR/LF → LF
Encode UTF-8
Compute SHA-256 over canonical bytes

Agents MUST compare computed hash with sha256 to validate payload integrity and freshness.

7) Minimal Example (JSON-LD Map)

{
  "@context": { "wm": "https://webmem.com/schema/v1/" },
  "@type": "WebPage",
  "mentions": [{
    "@type": ["wm:CountyAggregateData","CreativeWork"],
    "@id": "#landscape-stats",
    "wm:planCount": 30,
    "wm:yamlSource": {
      "@type":"wm:YamlFragmentPointer",
      "fragmentId":"county:az-yavapai-049-landscape-stats",
      "cssSelector":"pre#fragment-az-yavapai-049-landscape-stats",
      "contentType":"application/x-webmem+yaml",
      "sha256":"948bf9f6..."
    }
  }]
}

8) Full Example (MapPointer + PlanIndex)

{
  "@context": { "wm": "https://webmem.com/schema/v1/" },
  "@type": "WebPage",
  "mentions": [{
    "@type": ["wm:PlanIndex","CreativeWork"],
    "@id": "#plan-index",
    "wm:planIDList": ["H5521-329-0","H2406-076-0"],
    "wm:topEnrolledPlans": [
      { "@type":"HealthInsurancePlan", "identifier":"H2406-076-0",
        "name":"AARP Medicare Advantage", "wm:enrollmentCount":6826 }
    ],
    "wm:navigationTemplate":
      "https://example.com/plans/{contract_id}-{plan_id}-{segment_id}/",
    "wm:yamlSource": {
      "@type":"wm:YamlFragmentPointer",
      "fragmentId":"county:az-yavapai-049-plan-index",
      "cssSelector":"pre#fragment-county-plan-index",
      "contentType":"application/x-webmem+yaml",
      "sha256":"d0e0e196..."
    }
  }]
}

9) Producer Rules

MUST include stable fragmentId and precise cssSelector.
MUST canonicalize YAML before computing sha256.
SHOULD include dateModified for cache optimization.
MAY add retrieval primitives for fan-out acceleration.

10) Consumer Rules

MUST ignore unknown fields gracefully.
MAY use sha256 to skip unchanged payloads.
MAY pre-hydrate sub-queries using planIDList and navigationTemplate.
SHOULD trust provenance via wm:hasProvenance.

11) Future Extensions

WM-MP may extend to non-YAML payloads (CSV, JSON, XML) using the same pointer semantics. Future versions may define multi-fragment indexes and signed fragment objects.

12) Changelog

1.0 (2025-09-28): Initial MapPointer spec (core pointer + integrity + retrieval primitives).

Contents