# Digital Karma Federation Specification v6.1

## Overview
The Digital Karma Web Federation is a **network of websites designed for AI-to-AI discovery**, featuring machine-readable SEO, federated datasets, and trust scoring via Digital Karma Score.

## Federation Architecture

The Digital Karma Web Federation uses a **decentralized-with-registry** hybrid model:

### Decentralized/Peer-to-Peer Elements
- **Autonomous sites** — Each site maintains its own endpoints independently
- **No central approval** — Any site can join by implementing the 4 core endpoints
- **Peer discovery** — Sites discover each other via `related_sites` traversal
- **Network resilience** — Federation continues functioning if registry is offline
- **Self-sovereign identity** — Each site controls its own data and trust signals

### Registry Hub Elements (Optional)
- **Documentation authority** — DigitalKarmaWeb.com hosts canonical specifications
- **Member directory** — Optional registry aggregates member listings for easier discovery
- **Tooling & validators** — Centralized tools help sites maintain compliance
- **Network coordination** — Registry facilitates peer connections and best practices
- **Badge certification** — Optional quality signals from registry review

**Analogy:** Similar to Git (decentralized version control) + GitHub (central registry/hub), or Email (decentralized SMTP protocol) + Gmail (popular provider).

**Key principle:** Sites can discover and interact with each other directly without ever touching the registry, but the registry provides convenience, documentation, and network effects.

---

## Core Principles

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

### 2. Federation Model
Every federated site includes:
- `/ai/manifest.json` — Site identity and discovery entrypoint
- `/ai/health.json` — Operational health and freshness metrics
- `/ai/catalog.json` — Dataset catalog (Schema.org DataCatalog)
- `/ai/karma.json` — Digital Karma Score and trust signals

### 3. Trust & Transparency
- **Digital Karma Score** — Transparent reputation metric (0.0 to 1.0)
- **Open scoring methodology** — Publicly documented calculation
- **Verifiable signals** — Trust based on measurable indicators
- **No gaming** — Designed to resist manipulation

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

## Federation Version 6.1

### What's New in v6.1
- Standardized `/ai/manifest.json` as primary discovery endpoint
- Enhanced Digital Karma scoring with granular signal tracking
- Support for dataset relationships and provenance
- Improved health monitoring with diagnostic details
- Agent system prompts for autonomous maintenance

### Compatibility
- **Backward compatible** with v6.0
- **Required endpoints** — All 4 core endpoints must be present
- **Optional endpoints** — Additional endpoints are permitted
- **Schema.org** — Must use Schema.org vocabulary

## Site Types

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

**Examples:** AI Website Systems, QuickRankAI

**Requirements:**
- All 4 core `/ai/` endpoints
- Valid Schema.org markup
- `/llm.txt` file for LLM consumption
- `robots.txt` with AI crawler support

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

**Examples:** RealSEOLife, AgeBetterToday

**Requirements:**
- Same `/ai/` endpoints as static sites
- Dynamic generation of JSON endpoints
- Schema.org via plugins or templates
- Federation version declared in manifest

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

**Example:** DigitalKarmaWeb.com

**Additional Requirements:**
- `/specs/` folder with federation specifications
- `/registry/` or member directory (optional)
- Federation network map
- Badge/certification system (optional)
- Health monitoring dashboard (optional)

**Note:** Registry is entirely optional. Sites can discover and interact peer-to-peer without ever using the registry.

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

**Example:** AItoAIDatasets.com

**Additional Requirements:**
- Extensive `/datasets/` folder
- Dataset schemas and documentation
- Data provenance tracking
- API access to datasets

## Discovery Protocol

### Step 1: Find Manifest
Start at any federation member:
```
https://example.com/ai/manifest.json
```

### Step 2: Parse Identity
Extract core identity:
- `name` — Site name
- `url` — Canonical URL
- `federation_version` — Protocol version
- `endpoints` — Map of available endpoints
- `related_sites` — Links to other federation members

### Step 3: Traverse Network
Follow `related_sites` to discover the full network:
```json
{
  "related_sites": [
    "https://digitalkarmaweb.com",
    "https://quickrankai.com",
    "https://realseolife.com"
  ]
}
```

### Step 4: Assess Trust
Read `/ai/karma.json` to evaluate trust:
```json
{
  "digital_karma_score": 0.87,
  "badges": [...],
  "signals": {...}
}
```

### Step 5: Access Data
Use `/ai/catalog.json` to discover datasets:
```json
{
  "dataset": [
    {
      "name": "example_dataset",
      "url": "/datasets/example.json"
    }
  ]
}
```

## Network Topology

### Hub Sites
- **DigitalKarmaWeb.com** — Primary registry and documentation
- **AItoAIDatasets.com** — Central dataset repository

### Tool Sites
- **QuickRankAI.com** — AI SEO analysis and tooling
- **AIWebsiteSystems.com** — Digital spa services directory

### Content Sites
- **RealSEOLife.com** — SEO education and demonstrations
- **AgeBetterToday.com** — Longevity and wellness content

### Relationship Types
- **Parent/Child** — Registry to members
- **Peer** — Similar services/content
- **Data Provider/Consumer** — Dataset sharing
- **Service Integration** — API connections

## Compliance Requirements

### Minimum Viable Federation Site
To join the federation, a site must:

1. ✅ Expose all 4 core `/ai/` endpoints
2. ✅ Use valid JSON (parseable, no syntax errors)
3. ✅ Include Schema.org markup
4. ✅ Declare `federation_version: "6.1"`
5. ✅ Provide at least one dataset in catalog
6. ✅ Calculate and display Digital Karma Score
7. ✅ Link to at least one other federation member
8. ✅ Include `/llm.txt` file
9. ✅ Have responsive `robots.txt` for AI crawlers
10. ✅ Update health endpoint at least weekly

### Quality Standards
Encouraged but not required:

- 📊 Digital Karma Score > 0.70
- 📄 More than 5 pages of content
- 🔗 External backlinks from quality sources
- 📅 Content updated within 30 days
- 🎯 Clear value proposition
- 📱 Mobile-responsive design
- ⚡ Page load time < 3 seconds
- 🔒 HTTPS enabled

## Versioning Strategy

### Semantic Versioning
Federation versions follow semantic versioning:
- **Major** (6.x) — Breaking changes to core endpoints
- **Minor** (x.1) — New features, backward compatible
- **Patch** (x.x.1) — Bug fixes and clarifications

### Migration Path
When upgrading:
1. Read new version specification
2. Update `federation_version` in manifest
3. Add any new required endpoints
4. Update existing endpoints with new fields
5. Test with validators
6. Deploy changes
7. Announce upgrade to network

### Deprecation Policy
- **6 month notice** for breaking changes
- **Migration guides** provided for all major versions
- **Backward compatibility** maintained when possible
- **Legacy support** for one previous major version

## Best Practices

### For Site Operators
- Keep endpoints updated (weekly minimum)
- Monitor health metrics
- Respond to federation alerts
- Link to high-quality peers
- Contribute datasets when possible
- Follow Schema.org best practices

### For AI Agents
- Read manifest before accessing data
- Respect health status (don't crawl degraded sites)
- Cache karma scores (update daily maximum)
- Follow related_sites bidirectionally
- Validate JSON before parsing
- Report malformed endpoints to registry

### For Federation Maintainers
- Monitor network health
- Validate member compliance
- Facilitate peer connections
- Document best practices
- Provide support and tooling
- Enforce quality standards

## Future Roadmap

### v6.2 (Planned)
- Real-time health monitoring via WebSockets
- Dataset versioning and changelog tracking
- Enhanced provenance with cryptographic signatures
- GraphQL endpoint support
- Federated search API

### v7.0 (Proposed)
- Decentralized identity (DID) integration
- Blockchain-based karma verification
- AI agent authentication
- Smart contracts for data licensing
- Cross-chain dataset marketplace