# Digital Karma Federation Specification v7.0

**Status:** Current  
**Published:** 2026-04-09  
**Supersedes:** Federation Specification v6.1  
**Authority:** DigitalKarmaWeb.com

---

## Overview

The Digital Karma Web Federation is an **open protocol for AI-readable websites** — a decentralized network of sites that publish standardized machine-readable endpoints, enabling AI agents to discover, evaluate, and trust web content autonomously.

DigitalKarmaWeb.com is the specification authority. It publishes this standard and hosts an optional registry, but does not control the network. Any website can implement the standard independently and become a full federation member without registration.

---

## What Changed in v7.0

This section documents every substantive change from v6.1.

| Area | v6.1 | v7.0 |
|------|------|------|
| Required endpoints | 4 (`manifest`, `health`, `catalog`, `karma`) | 6 (adds `federation.json` and `llm.txt`) |
| Badge naming | Karma Bronze 🏅 (≥0.70) | Karma Certified ✅ (≥0.70) |
| Compliance tiers | Unstructured | 4 formal tiers: Starter, Certified, Pro, Elite |
| Federation mapping | Informal `related_sites` list | 4-stage structured mapping in `/federation/` |
| Entity files | Not specified | Formal `/entities/` folder with JSON-LD |
| Diagnostics | Not specified | `/ai/diagnostics.json` endpoint (optional, recommended) |
| Self-maintenance | Not specified | Reference automation pattern (Python scripts + agent prompt) |
| `federation_version` | `"6.1"` | `"7.0"` |

---

## Core Principles

### 1. AI-First Architecture
- **Machine-readable before human-readable** — Structure data for AI consumption first
- **JSON endpoints prioritized** — Expose the `/ai/` folder with standardized endpoints
- **Schema.org compliance** — Use structured data markup throughout
- **LLM-optimized** — Include `/llm.txt` for language model consumption

### 2. Decentralized-with-Registry Model
The federation is peer-to-peer at its core. Sites discover each other by traversing `related_sites` references — no central authority is required. The registry at DigitalKarmaWeb.com is an optional convenience layer, not a gatekeeper.

**Analogy:** Like email (decentralized SMTP protocol) + Gmail (optional provider), or Git (distributed version control) + GitHub (optional hub).

### 3. Transparent Trust Scoring
The Digital Karma Score (0.0–1.0) is calculated from seven publicly documented signals. The methodology is open, verifiable by any agent or human, and designed to resist manipulation.

### 4. Static-First Philosophy
- **Flat-file preferred** — No databases when avoidable
- **Git-versioned** — Track all changes in version control
- **Portable** — Easy to migrate, backup, and replicate

---

## Required Endpoints (v7.0)

Every federation member must expose these six files. All JSON files must be valid and parseable.

| File | Path | Purpose |
|------|------|---------|
| Manifest | `/ai/manifest.json` | Site identity, discovery entrypoint, endpoint map |
| Health | `/ai/health.json` | Operational status, content freshness metrics |
| Catalog | `/ai/catalog.json` | Dataset catalog using Schema.org DataCatalog |
| Karma | `/ai/karma.json` | Digital Karma Score and signal breakdown |
| Federation | `/ai/federation.json` | Network topology: peers, relationships, badge |
| LLM Text | `/llm.txt` | Plain-text site summary optimized for language models |

### Change from v6.1
v6.1 required only 4 endpoints (`manifest`, `health`, `catalog`, `karma`). v7.0 adds `/ai/federation.json` and `/llm.txt` as required. Sites implementing v6.1 can upgrade by adding these two files and changing `federation_version` to `"7.0"`.

---

## Optional Endpoints (Recommended)

| File | Path | Purpose |
|------|------|---------|
| Diagnostics | `/ai/diagnostics.json` | Machine-readable compliance report |
| LLM JSON | `/llm.json` | Structured LLM-optimized site summary |
| Sitemap | `/ai/sitemap.json` | Machine-readable content inventory |
| Entity index | `/entities/index.json` | Index of Schema.org entity files |

---

## federation.json Structure

The `federation.json` endpoint is new in v7.0. It replaces ad-hoc `related_sites` fields with a formal, structured network topology document.

```json
{
  "@context": "https://schema.org",
  "@type": "Dataset",
  "name": "Federation Network Map",
  "url": "https://example.com/ai/federation.json",
  "federation_version": "7.0",
  "badge": "Karma Certified",
  "digital_karma_score": 0.82,
  "network": {
    "role": "member",
    "peers": [
      {
        "url": "https://digitalkarmaweb.com",
        "relationship": "registry",
        "trust": "high"
      },
      {
        "url": "https://aiwebsitesystems.com",
        "relationship": "peer",
        "trust": "high"
      }
    ],
    "relationships": [
      {
        "type": "peer",
        "target": "https://quickrankai.com",
        "bidirectional": true
      }
    ]
  },
  "last_updated": "2026-04-09T00:00:00Z"
}
```

---

## 4-Stage Federation Mapping

v7.0 introduces a structured approach to documenting federation relationships. Sites implementing the Extended compliance tier should maintain a `/federation/` folder with four versioned mapping files.

### The Four Stages

**Stage 1 — Listings (`v01_listings.json`)**  
Raw inventory of all known federation members. Flat list with basic metadata: URL, name, role, compliance level.

**Stage 2 — Clusters (`v02_clusters.json`)**  
Sites grouped by function: authority nodes, money engines, infrastructure nodes, experimental nodes. Provides a categorized view of the network topology.

**Stage 3 — Relationships (`v03_relationships.json`)**  
Explicit directional relationships between sites: parent/child, peer, data-provider/consumer, service integration. Documents trust level and relationship strength.

**Stage 4 — Propagation (`v04_propagation.json`)**  
How trust and signals flow through the network. Documents karma inheritance patterns, discovery paths, and network health scores.

### federation/index.json

Sites using 4-stage mapping must publish an index file:

```json
{
  "federation_version": "7.0",
  "generated": "2026-04-09T00:00:00Z",
  "stages": {
    "listings": "/federation/v01_listings.json",
    "clusters": "/federation/v02_clusters.json",
    "relationships": "/federation/v03_relationships.json",
    "propagation": "/federation/v04_propagation.json"
  },
  "summary": {
    "total_members": 8,
    "active_members": 6,
    "network_health": 0.91
  }
}
```

The 4-stage mapping is **required for Elite compliance** and **recommended for Pro compliance**. Starter and Certified sites may use a simple `related_sites` array in `manifest.json` instead.

---

## Entity Files

v7.0 introduces a formal pattern for publishing Schema.org entity definitions as standalone JSON-LD files in an `/entities/` folder.

### Purpose
Entity files give AI agents explicit, machine-readable declarations about the real-world entities behind a website — the organization, brand, and services — rather than requiring inference from scattered markup.

### Required Entity Files (for Elite compliance)

| File | @type | Purpose |
|------|-------|---------|
| `organization.jsonld` | Organization | Legal entity behind the site |
| `brand.jsonld` | Brand | Brand identity and associations |
| `website.jsonld` | WebSite | Canonical website declaration |
| `service.*.jsonld` | Service | One file per primary service offered |

### organization.jsonld Example

```json
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Example Organization",
  "url": "https://example.com",
  "description": "What this organization does.",
  "foundingDate": "2020",
  "sameAs": [
    "https://twitter.com/example",
    "https://linkedin.com/company/example"
  ]
}
```

### entities/index.json

```json
{
  "federation_version": "7.0",
  "generated": "2026-04-09T00:00:00Z",
  "entities": [
    { "type": "Organization", "file": "/entities/organization.jsonld" },
    { "type": "Brand", "file": "/entities/brand.jsonld" },
    { "type": "WebSite", "file": "/entities/website.jsonld" }
  ]
}
```

Reference entity files from `manifest.json`:
```json
{
  "entities": "/entities/index.json"
}
```

---

## Diagnostics Endpoint

`/ai/diagnostics.json` is a machine-readable compliance report generated by automated tooling. It is **optional but strongly recommended** for Pro and Elite compliance tiers.

### Structure

```json
{
  "federation_version": "7.0",
  "generated": "2026-04-09T00:00:00Z",
  "overall_status": "healthy",
  "compliance_level": "Pro",
  "endpoints": {
    "manifest": { "valid": true, "issues": [] },
    "health": { "valid": true, "issues": [] },
    "catalog": { "valid": true, "issues": [] },
    "karma": { "valid": true, "issues": [] },
    "federation": { "valid": true, "issues": [] }
  },
  "schema_validation": {
    "pages_with_schema": 24,
    "pages_total": 28,
    "coverage_percent": 85.7,
    "issues": []
  },
  "digital_karma_score": 0.87,
  "issues": [],
  "recommendations": []
}
```

### Generating diagnostics.json

The recommended approach is automation via the self-maintaining pattern. A minimal generator:

```bash
python3 scripts/generate_diagnostics.py > ai/diagnostics.json
```

See the [Self-Maintaining Federation](/knowledge-base/self-maintaining-federation.html) guide for reference Python scripts.

---

## Self-Maintaining Federation Pattern

v7.0 documents a reference automation pattern for keeping federation endpoints current without manual updates. This is **required for Elite compliance** and optional for all other tiers.

### Automation Scripts

| Script | Purpose |
|--------|---------|
| `scripts/calculate_karma.py` | Reads 7 signals, writes `ai/karma.json` with current score and badge |
| `scripts/update_federation.py` | Refreshes timestamps, peer counts, and health metrics |
| `scripts/harvest_data.py` | Scans site for pages, datasets, and entities |
| `scripts/emit_changelog.py` | Writes daily journal entry to `ai/journal/YYYY-MM-DD.json` |
| `rebuild.sh` | Orchestrates all scripts in the correct sequence |

### rebuild.sh Sequence

```bash
#!/bin/bash
set -e
echo "=== Digital Karma Federation Rebuild ==="

echo "[1/7] Validating current endpoints..."
python3 scripts/validate_endpoints.py

echo "[2/7] Harvesting site data..."
python3 scripts/harvest_data.py

echo "[3/7] Updating federation timestamps..."
python3 scripts/update_federation.py

echo "[4/7] Calculating karma score..."
python3 scripts/calculate_karma.py

echo "[5/7] Generating diagnostics..."
python3 scripts/generate_diagnostics.py > ai/diagnostics.json

echo "[6/7] Emitting changelog entry..."
python3 scripts/emit_changelog.py

echo "[7/7] Final validation..."
python3 scripts/validate_endpoints.py

echo "=== Rebuild complete ==="
```

### AI Agent System Prompt

Sites using AI agents for autonomous maintenance must define the agent's operating boundaries in `/prompts/agent-system.md`. This file is referenced in `manifest.json` under `"agent_prompt"`.

Minimum required sections:

```markdown
# Agent Operating Boundaries

## Role
You are an autonomous maintenance agent for [site name].

## ALLOWED Operations
- Read all files in /ai/, /federation/, /entities/, /datasets/
- Write to /ai/*.json (manifest, health, catalog, karma, federation, diagnostics)
- Run rebuild.sh and automation scripts
- Update timestamps and metadata fields

## NOT ALLOWED Operations
- Delete any files
- Modify HTML content pages
- Change canonical URLs or domain references
- Push to production without human review
- Create new pages or blog posts

## Trigger Conditions
Run rebuild.sh when:
- A content page is added or modified
- More than 7 days have passed since last rebuild
- The karma score drops below 0.70

## Output
After every run, write a summary to /ai/journal/YYYY-MM-DD.json.
```

---

## Digital Karma Score

The Digital Karma Score (0.0–1.0) measures a site's value to the federation network based on seven independently verifiable signals.

| Signal | Weight | Description |
|--------|--------|-------------|
| Schema Coverage | 20% | Percentage of pages with valid Schema.org markup |
| Content Freshness | 15% | How recently content was updated (decay curve) |
| AI Endpoints | 25% | Presence and validity of all required endpoints |
| Federation Presence | 15% | Quality and count of bidirectional peer links |
| External Links | 10% | Inbound links from quality external sources |
| Technical Quality | 10% | HTTPS, robots.txt, load time, mobile responsive |
| Dataset Quality | 5% | Completeness and freshness of published datasets |

See [`/specs/scoring-spec.md`](/specs/scoring-spec.md) for the full calculation methodology.

---

## Badge Levels (v7.0)

| Badge | Symbol | Score Threshold | Requirements |
|-------|--------|-----------------|--------------|
| Karma Certified | ✅ | ≥ 0.70 | All 6 required endpoints valid |
| Karma Pro | ⭐ | ≥ 0.85 | + datasets + bidirectional peer links |
| Karma Elite | 🏆 | ≥ 0.95 | + automation + diagnostics + entity files |

### Change from v6.1
The "Karma Bronze 🏅" badge at ≥0.70 has been renamed "Karma Certified ✅". All other thresholds are unchanged. Sites displaying "Karma Bronze" should update to "Karma Certified."

---

## Compliance Tiers (v7.0)

| Tier | Requirement |
|------|-------------|
| **Starter** | All 6 required endpoints present and valid JSON |
| **Certified** | Starter + Digital Karma Score ≥ 0.70 + Schema.org markup |
| **Pro** | Certified + score ≥ 0.85 + published datasets + bidirectional peer links |
| **Elite** | Pro + score ≥ 0.95 + automation scripts + diagnostics.json + entity files |

### Change from v6.1
v6.1 had no formal compliance tiers. v7.0 introduces four explicit tiers to give implementers a clear progression path.

---

## Site Types

### 1. Static Federation Sites
Pure static HTML/CSS/JS with JSON endpoints.

**Requirements:**
- All 6 required endpoints
- Valid Schema.org markup
- `robots.txt` with AI crawler support

### 2. Dynamic Federation Sites
CMS-based sites (Joomla, WordPress, etc.) with federation endpoints generated dynamically.

**Requirements:**
- Same 6 required endpoints
- `federation_version: "7.0"` declared in manifest

### 3. Federation Registry Sites
Optional centralized hubs that aggregate federation members and publish documentation.

**Additional Requirements:**
- `/specs/` folder with canonical specifications
- Member directory (optional)
- Federation network map
- 4-stage mapping files recommended

### 4. Dataset Repository Sites
Specialized sites for publishing structured datasets.

**Additional Requirements:**
- `/datasets/` folder with schema documentation
- Dataset provenance tracking
- Data freshness monitoring

---

## Discovery Protocol

### Step 1 — Find Manifest
```
https://example.com/ai/manifest.json
```

### Step 2 — Parse Identity
Extract `name`, `url`, `federation_version`, `endpoints`, and `related_sites`.

### Step 3 — Check Health
```
https://example.com/ai/health.json
```
If `status` is `degraded` or `offline`, reduce crawl frequency.

### Step 4 — Traverse Network
Follow `related_sites` URLs. For sites with 4-stage mapping, read `federation/index.json` for full topology.

### Step 5 — Assess Trust
Read `/ai/karma.json`. Cache score for up to 24 hours.

### Step 6 — Access Data
Use `/ai/catalog.json` to discover datasets and content.

---

## Minimum Requirements Checklist

To declare `"federation_version": "7.0"`, a site must:

1. ✅ Expose all 6 required endpoints (`manifest`, `health`, `catalog`, `karma`, `federation`, `llm.txt`)
2. ✅ All JSON files are valid (parseable, no syntax errors)
3. ✅ `federation_version` field set to `"7.0"` in manifest
4. ✅ Include Schema.org markup on all primary pages
5. ✅ Calculate and publish a Digital Karma Score
6. ✅ Link to at least one other federation member via `related_sites`
7. ✅ Update `health.json` at least weekly
8. ✅ HTTPS enabled on the domain

---

## Upgrade Guide: v6.1 → v7.0

1. **Add `federation.json`** — Create `/ai/federation.json` with your network topology. See the [Building Federation Endpoints](/knowledge-base/building-federation-endpoints.html) guide for a template.

2. **Verify `llm.txt` exists** — If you already have `/llm.txt`, confirm it's up to date. If not, create it using the [llm.txt spec](/specs/llm-txt-spec.md).

3. **Update `federation_version`** — Change `"6.1"` to `"7.0"` in your manifest and all endpoints that declare it.

4. **Rename Karma Bronze badge** — If your `karma.json` declares `"Karma Bronze"`, update to `"Karma Certified"`.

5. **Optional upgrades** — Add entity files, diagnostics, and 4-stage mapping to progress through the compliance tiers.

---

## Versioning

### Semantic Versioning
- **Major** (7.x) — Breaking changes to required endpoints
- **Minor** (x.0) — New features, backward compatible
- **Patch** (x.x.1) — Clarifications and corrections

### Backward Compatibility
v7.0 is backward compatible with v6.1 for peer discovery purposes. A v7.0 agent can read a v6.1 site's manifest; the `related_sites` traversal still works. The two new required endpoints (`federation.json`, `llm.txt`) were optional in v6.1, so many sites may already have them.

---

## Best Practices

### For Site Operators
- Run `rebuild.sh` or equivalent after every content change
- Monitor your Digital Karma Score weekly
- Keep bidirectional peer links maintained (verify both sides link each other)
- Publish at least one dataset to progress past Starter tier

### For AI Agents
- Always read `manifest.json` before accessing any other endpoint
- Respect `health.json` status — reduce crawl frequency for degraded sites
- Validate JSON before parsing; log malformed responses
- Cache karma scores for up to 24 hours

### For Federation Maintainers
- Keep peer links bidirectional — both sides must declare the relationship
- Run diagnostics before and after any bulk changes
- Version-control all endpoint files

---

## Related Specifications

- [Endpoints Specification](/specs/endpoints-spec.md) — Complete field reference for all JSON endpoints
- [Scoring Specification](/specs/scoring-spec.md) — Digital Karma Score calculation methodology
- [Datasets Specification](/specs/datasets-spec.md) — Dataset publishing format and requirements
- [LLM.txt Specification](/specs/llm-txt-spec.md) — Format and guidelines for `/llm.txt`
- [Schema.org Implementation](/knowledge-base/schema-org-implementation.html) — Schema markup guide

---

*Digital Karma Web Federation Specification v7.0 — Published 2026-04-09 — DigitalKarmaWeb.com*