# Digital Karma Federation Specification v8.0

**Status:** Current
**Published:** 2026-07-29
**Supersedes:** Federation Specification v7.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.

**Note on terminology:** a 2026-05-11 proposal to rename Federation concepts to "Constellation" language (Sites -> Stars, endpoints -> Signals, cross-site links -> Alignments) was considered and dropped -- see `data/digital-karma-history.json`. It was never implemented anywhere in the portfolio. "Constellation" continues to mean what it always has here: the grouping concept krisada.com's directory uses (healthcare-ai-longevity, one-mouse-marketing, etc.). This spec does not use Stars/Signals/Alignments.

---

## v8.0 Major Revision

v8.0 is an architectural revision, not a terminology change. v7.1 made every federation member individually compliant, but each site still hand-rolled its own generator script and schema markup -- duplication that was the direct, traceable cause of most federation-related bugs across the portfolio (empty catalogs, stale constellation references, wrong sitemap roots, missing files, drifted `related_sites`). v8.0 closes that gap with a shared, config-driven generation engine instead of per-site reinvention.

It formalizes these rules:

- Every generated `/ai/*.json` file carries a `protocol_version` field plus a real lifecycle (`supported_since`, `deprecated_after`, `removed_after`) instead of an implicit "probably still fine."
- `llm.json` (and `/ai/llm.json`) is retired. `/ai/manifest.json` carries the same identity fields a separate `llm.json` would have -- one document instead of two that can silently drift apart. `/llm.txt` (plain text) is unchanged and still required.
- `related_sites` should be resolved from a single canonical source (a `constellations.json` export, see below) rather than hand-typed per site. Hand-typed lists are the single most common source of federation drift found in this revision.
- `robots.txt`, where machine-generated, should be produced from explicit per-endpoint visibility declarations (`public | federation | internal | private`) rather than hand-audited -- this retires a real, recurring bug class where a site's own manifest advertised an endpoint its `robots.txt` then blocked.

---

## What Changed in v8.0

This section documents every substantive change from v7.1. Unlike the "Self-Maintaining Federation Pattern" described in v7.1 (Python scripts, `rebuild.sh`, an agent system prompt) -- which was a proposed pattern, not something ever actually deployed across the portfolio -- this section describes the real, live mechanism as of this revision.

| Area | v7.1 | v8.0 |
|------|------|------|
| Generation model | Each site hand-writes or hand-maintains its own generator | A shared reference template (`build-federation-template.php`) backs a portfolio-wide rollout script; sites with bespoke architecture (single-file bootstrap patterns, non-standard content layouts) get a purpose-built generator following the same output contract |
| `llm.json` | Optional endpoint | Retired. Do not create it; do not delete existing copies automatically (see Migration Notes) |
| Protocol/lifecycle metadata | Not specified | Required: `protocol_version`, `supported_since`, `deprecated_after`, `removed_after` on every generated file |
| `related_sites` | Hand-typed per site | Should resolve from a canonical `constellations.json` export where one is available |
| `robots.txt` | Hand-audited | Should be generated from declared endpoint visibility where the site has a real generator |
| `federation_version` | `"7.1"` | `"8.0"` |

### Real automation, not the v7.1 Python pattern

v7.1's "Self-Maintaining Federation Pattern" described `scripts/calculate_karma.py`, `rebuild.sh`, and a `/prompts/agent-system.md` boundary file. That pattern was aspirational and was never the actual mechanism running anywhere in this portfolio. As of v8.0, the real, live automation is:

- **`vps-scripts/rollout-federation-v71.php`** -- scans every eligible site (one with `config/site.json` + a root `index.php`), derives `related_sites`/constellation/tier metadata from krisada.com's own directory listings, and regenerates each site's `/ai/*` output by running its own generator.
- **`vps-scripts/build-federation-template.php`** -- the canonical, unpatched reference generator. The rollout script reads this file fresh every run, applies portfolio-wide patches (`patch_template_source()`), and writes the patched result into each eligible site's own `scripts/build-federation.php`. This file is never itself a live site's generator -- keeping the read-source and every write-target as separate files is what makes patch-based updates safe to re-run.
- **Bespoke generators** -- sites with genuinely different architecture (a single-file `bootstrap.php` request handler, or a content layout the shared template's collection scanner doesn't recognize) get a purpose-built generator that still emits the same output contract (protocol/lifecycle fields, `constellations.json`-resolved siblings, no `llm.json`) using that site's own real content-loading code instead of the shared template's assumptions.
- **`--only=host1,host2`** -- the rollout script supports scoping a run to specific hosts, for testing a template change against a small set of real sites before a full portfolio run.

---

## Required Endpoints (v8.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 |

No change to this list from v7.1 -- the six required endpoints are unchanged. What changed is what each one must contain (protocol/lifecycle metadata) and, where `llm.json` previously existed, that it should not.

### Protocol/lifecycle metadata (new, required)

Every one of the six endpoints above must carry these four fields:

```json
{
  "protocol_version": "8.0",
  "supported_since": "2026-07-29",
  "deprecated_after": null,
  "removed_after": null
}
```

`deprecated_after` and `removed_after` are `null` until a specific field or endpoint is deliberately marked for retirement -- a version bump alone never implies deprecation. When something is deprecated, set a real date in these fields rather than removing the field silently.

---

## Optional Endpoints (Recommended)

| File | Path | Purpose |
|------|------|---------|
| Diagnostics | `/ai/diagnostics.json` | Machine-readable compliance report |
| XML Sitemap | `/sitemap.xml` | Canonical crawl sitemap at the site root |
| Sitemap JSON | `/ai/sitemap.json` | Optional machine-readable content inventory companion |
| Entity index | `/entities/index.json` | Index of Schema.org entity files |

`llm.json` has been removed from this table (see Migration Notes -- it is retired, not merely optional).

---

## Root Discovery Rule

`robots.txt` and `sitemap.xml` must live at the site root. Do not relocate either file into `/ai/`. Unchanged from v7.1.

---

## robots.txt Generation (new in v8.0)

Where a site has a real generator, `robots.txt` should be produced from explicit endpoint visibility declarations rather than hand-audited:

```php
$endpointVisibility = [
    '/ai/'      => 'public',
    '/api/v1/'  => 'public',
    '/admin/'   => 'private',
    '/data/'    => 'internal',
];
```

`public` and `federation` visibility become `Allow`; `internal` and `private` become `Disallow`. This retired a real bug found during this revision: a site's own `/ai/manifest.json` advertised a public content API under `/api/v1/` while its hand-maintained `robots.txt` blocked crawlers from that exact path. Generating both from the same declared-visibility source makes that contradiction structurally impossible instead of something to catch by hand.

Sites without a real generator should still audit for this specific contradiction manually: does anything your manifest/catalog advertises as a public endpoint get blocked in `robots.txt`?

---

## federation.json Structure

Unchanged in shape from v7.1, with the protocol/lifecycle fields added at the top level:

```json
{
  "protocol_version": "8.0",
  "supported_since": "2026-07-29",
  "deprecated_after": null,
  "removed_after": null,
  "@context": "https://schema.org",
  "@type": "Dataset",
  "name": "Federation Network Map",
  "url": "https://example.com/ai/federation.json",
  "federation_version": "8.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-07-29T00:00:00Z"
}
```

---

## Resolving related_sites from constellations.json (new in v8.0)

Hand-typed `related_sites` lists were found, during this revision, to be the single most common source of federation drift in the portfolio -- several sites had `related_sites` listing only 1 of 8 to 16 real siblings, sometimes referencing sites from a completely different grouping. Where a canonical `constellations.json` export is available (a site-inventory JSON keyed by constellation slug, listing every member domain), a generator should resolve real siblings from it directly:

```json
{
  "constellations": [
    {
      "slug": "healthcare-ai-longevity",
      "title": "Healthcare AI & Longevity",
      "domains": ["agebettertoday.com", "aihealthcarenow.com", "..."]
    }
  ]
}
```

For each domain in the site's own constellation (excluding itself), emit a `related_sites` entry with `relationship: "constellation_peer"`. Domains that already carry a subdomain (e.g. `power11.as400ibmsystem.com`) should be used as-is; bare apex domains get the canonical `https://www.` form. This does not replace explicitly-declared relationships (e.g. a `protocol_keeper` reference to DigitalKarmaWeb.com) -- merge the two, with explicit declarations taking precedence on conflict.

---

## 4-Stage Federation Mapping

Unchanged from v7.1. Sites implementing the Extended compliance tier should maintain a `/federation/` folder with four versioned mapping files (`v01_listings.json`, `v02_clusters.json`, `v03_relationships.json`, `v04_propagation.json`) plus an `index.json`. See the v7.1 spec's description of this pattern for the full structure -- it did not change in v8.0.

One correction from this revision: cluster/mapping files describing constellation membership must be regenerated from the canonical `constellations.json` source, not hand-authored -- a hand-authored `v02_clusters.json` on this very site was found to be three weeks stale relative to the real membership, missing an entire constellation split and several domains, before being fixed as part of this revision.

---

## Entity Files

Unchanged from v7.1. See that spec's description of the `/entities/` folder pattern, required files for Elite compliance, and `entities/index.json` structure.

---

## Diagnostics Endpoint

Unchanged in structure from v7.1, with `protocol_version`/lifecycle fields added at the top level like every other endpoint.

---

## Digital Karma Score

Unchanged from v7.1 -- the seven-signal weighted methodology is not part of this revision. See [`/specs/scoring-spec.md`](/specs/scoring-spec.md) for the full calculation methodology.

| 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 |

**Known limitation, unresolved in this revision:** on several sites, `digital_karma_score` and its signal breakdown are still static defaults, not measured from anything real. "Karma Certified" currently means "has the right files present," not "scored well by an evaluation." Don't present the score as more meaningful than that until real measurement exists.

---

## Badge Levels

Unchanged from v7.1.

| 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 |

---

## Compliance Tiers

Unchanged from v7.1.

| 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 |

---

## Site Types

Unchanged from v7.1: Static Federation Sites, Dynamic Federation Sites, Federation Registry Sites, Dataset Repository Sites. See that spec for full requirements per type; only `federation_version` in the Dynamic type's requirement changes, to `"8.0"`.

---

## Discovery Protocol

Unchanged from v7.1 -- manifest first, then health, then network traversal via `related_sites` or `federation/index.json`, then karma, then catalog.

---

## Minimum Requirements Checklist

To declare `"federation_version": "8.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 `"8.0"` in manifest
4. Every generated endpoint carries `protocol_version`/`supported_since`/`deprecated_after`/`removed_after`
5. Does not create or maintain `llm.json` / `/ai/llm.json`
6. Include Schema.org markup on all primary pages
7. Calculate and publish a Digital Karma Score
8. Link to at least one other federation member via `related_sites`, resolved from `constellations.json` where available rather than hand-typed
9. Update `health.json` at least weekly
10. HTTPS enabled on the domain

---

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

1. **Add protocol/lifecycle fields** - Merge `protocol_version: "8.0"`, `supported_since`, `deprecated_after: null`, `removed_after: null` into every generated endpoint.

2. **Stop writing `llm.json`** - Remove the generator step that writes `/llm.json` and `/ai/llm.json`, and remove any `llm_json`/`llm_json_legacy` entries from your `endpoints` map and any `datasets`/manifest entries referencing them. Do not delete the existing files automatically (see Migration Notes) -- just stop regenerating them.

3. **Wire `related_sites` to `constellations.json`** - If a canonical constellations export is available to your generator, resolve real siblings from it instead of a hand-typed list. Audit your current list first: it is very likely missing real siblings.

4. **Update `federation_version`** - Change `"7.1"` to `"8.0"` in your manifest and all endpoints that declare it.

5. **If you generate `robots.txt`** - Move to visibility-declaration generation and check specifically for the "manifest advertises it, robots.txt blocks it" contradiction.

### Migration Notes: llm.json

Existing `llm.json`/`ai/llm.json` files are not deleted by this revision on any site where they already existed -- they simply stop being regenerated, and will grow stale over time. A dedicated cleanup pass to remove them portfolio-wide has not yet been done as of this spec's publication. Do not treat an orphaned `llm.json` on a given site as an active bug; it is a known, tracked cleanup item.

---

## Versioning

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

### Backward Compatibility
v8.0 is backward compatible with v7.1 for peer discovery purposes. A v8.0 agent can read a v7.1 site's manifest; `related_sites` traversal still works. The new required protocol/lifecycle fields are additive -- their absence should be treated as "not yet upgraded," not as invalid.

---

## Best Practices

### For Site Operators
- Regenerate federation files after every content change, via whatever mechanism your site actually uses (shared rollout script, bespoke generator, or manual)
- Monitor your Digital Karma Score, understanding its current limitations (see above)
- Keep bidirectional peer links maintained (verify both sides link each other)
- If your site predates `config/site.json` and isn't covered by the shared rollout, say so explicitly in your own documentation rather than leaving it ambiguous whether the site is compliant

### 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
- Treat a missing `protocol_version` field as "pre-v8.0," not as an error

### For Federation Maintainers
- Keep peer links bidirectional - both sides must declare the relationship
- When patching the shared template, test against a small `--only=` scope before a full portfolio run
- Never let a site's own live generator also be the template other sites' generators are patched from -- keep the canonical read-source separate from every write-target

---

## 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
- [Federation Specification v7.1](/specs/federation-spec-v7.md) - Predecessor spec, kept for history

---

*Digital Karma Web Federation Specification v8.0 - Published 2026-07-29 - DigitalKarmaWeb.com*