Specification / v0.1

Grounding Map Specification

A Grounding Map is a directory-based index layer that connects a website's Grounding Pages, explanatory articles, evidence pages and machine-readable resources.

Specification v0.1 starts with website architecture, not abstract entity modeling. It is derived from the /fakten/ implementation on marcdeboer.de.

Definition

Architecture model

The map is a crawlable directory and index page. It names the stable Grounding Pages in that directory, links them to editorial explanations, records evidence and points to machine-readable companions.

1. Grounding Map Directory

A stable website directory such as /facts/ or /fakten/.

2. Grounding Map Index Page

The landing page at that directory. It lists Grounding Pages and shows how they connect.

3. Grounding Page

A stable page for one named entity or concept, for example /fakten/search-reality/.

4. Relationship Layer

Typed links between the map index, Grounding Pages, related pages, articles and resources.

5. Evidence Layer

URLs that support a page or relationship, including facts pages, articles, source references and registries.

6. Editorial Explanation Layer

Articles or guides that explain why a Grounding Page exists and how the concept is used.

7. Machine-readable Layer

.md.txt, llms.txt, JSON resources, structured data and optional discovery endpoints later.

8. Reference Implementation

The first external reference implementation used to derive Specification v0.1 is marcdeboer.de/fakten/.

9. Versioning and Status

Version 0.1 is experimental. It defines structure, not adoption, certification or results.

Architecture fields

Required and optional fields

The field model follows the directory architecture. Entity fields are only useful when they belong to a map index and a specific Grounding Page.

Field	Required	Description
`mapDirectory`	yes	Directory path for the map, for example `/facts/` or `/fakten/`.
`mapIndexUrl`	yes	Absolute URL of the Grounding Map Index Page.
`groundingPageUrl`	yes	Absolute URL of the stable Grounding Page.
`entityName`	yes	Public entity or concept name.
`entityType`	yes	Person, Organization, Concept, Method, Product, Topic, Dataset or Standard.
`canonicalReference`	yes	The canonical reference URL. Usually this is the Grounding Page URL.
`editorialExplanationUrl`	recommended	Main article, guide or explainer that contextualizes the Grounding Page.
`evidenceUrls`	yes	Pages, source references or examples that support the page or relationship.
`relatedGroundingPages`	recommended	Related Grounding Page URLs or IDs.
`relationshipType`	yes	The role of the relationship, using the controlled vocabulary below.
`machineReadableUrl`	recommended	Link to `.md.txt`, JSON or another machine-readable companion.
`status`	yes	`active`, `emerging`, `parked` or `deprecated`.
`stability`	yes	`stable`, `evolving`, `parked` or `replaced`.
`lastReviewed`	yes	Date of the last editorial review.
`openGaps`	recommended	Visible gap, missing evidence or unclear boundary note.

Relationship Layer

Controlled vocabulary

defines: formulates canonical meaning.
explains: provides context or rationale.
supports: supplies evidence for a claim.
extends: builds on an existing concept.
differentiates: clarifies boundaries.
operationalizes: makes a concept usable.
aggregates: bundles pages or references.
structures: organizes the map index.
is_source_for: acts as a primary source.
is_reference_implementation_for: documents the first implementation used to derive v0.1.

Versioning and Status

Experimental v0.1

Version 0.1 describes a structure that can be inspected and maintained. It does not claim external adoption, certification, ranking impact or performance outcomes.

Evidence Layer

Evidence is editorial, not a score

Evidence URLs should show where the relationship can be inspected. They do not produce a quality score or automatic validation.

Reference Implementation

marcdeboer.de/fakten/

The first reference implementation used to derive Specification v0.1 is marcdeboer.de/fakten/. The map index connects Grounding Pages such as Grounding Map, SEO-Entropie and Search Reality with the editorial explanation at /blog/grounding-map/ and machine-readable resources such as .md.txt, llms.txt and JSON exports.

This site now also contains its own minimal Reference Implementation at /facts/, with Grounding Pages for Grounding Map and Marc de Boer.

This reference is not a claim that the implementation is perfect or that the method is an established external standard.

Use the template View JSON Schema