Digital Karma Web Standards & Architecture

🌐 Federation Protocol v7.0

The Digital Karma Web Federation is an open standard enabling any AI-ready website to join a decentralized network of machine-readable sites. Sites discover, understand, and trust each other through standardized endpoints and transparent reputation scoring. DigitalKarmaWeb.com is the specification authority — any site can implement the standard independently.

Core Principles

1. Discoverability — Sites expose predictable endpoints at /ai/*
2. Interoperability — All endpoints use standard JSON formats
3. Transparency — Quality scores are calculated openly and verifiably
4. Decentralization — No central authority required; peer-to-peer discovery works without the registry
5. Self-Sovereignty — Each site controls its own data and trust signals
6. Versioning — Protocol versioning for backward compatibility

What Changed in v7.0

Compliance Levels

Read Full Federation Spec →

📋 Manifest Specification (/ai/manifest.json)

The primary discovery file. A crawler or agent should be able to start here and understand what the site is, what version it runs, and where the other endpoints live.

Required Fields

{
  "name": "string",               // Site name
  "url": "string",                // Canonical URL
  "federation_version": "7.0",   // Must be "7.0"
  "updated_utc": "ISO8601",       // UTC timestamp
  "endpoints": {                  // Map of key endpoint URLs
    "health": "/ai/health.json",
    "catalog": "/ai/catalog.json",
    "karma": "/ai/karma.json",
    "federation": "/ai/federation.json"
  },
  "related_sites": ["https://www.aiwebsitesystems.com"]
}

Recommended Fields

• description — Short site description
• tagline — One-line positioning statement
• contact — Email and website of maintainer
• related_sites — Array of federation partner URLs
• datasets — Summary of available datasets
• services — Array of service offerings
• schema_org_types — Implemented Schema.org types

💓 Health Endpoint (/ai/health.json)

Reports operational readiness and content freshness. Keep timestamps current — weekly refresh is the minimum baseline.

Required Fields

{
  "site": "https://example.com",
  "status": "ok|ready|degraded|offline|down",
  "updated_utc": "ISO8601",
  "metrics": {
    "pageCount": number,
    "datasetCount": number,
    "entityCount": number
  }
}

Recommended Fields

• last_rebuild_utc — Date of last site rebuild
• checks — Presence validation of required endpoints
• endpoints — Key endpoint URLs
• notes — Human-readable status notes

📚 Catalog Endpoint (/ai/catalog.json)

The site's machine-readable catalog of datasets, endpoints, and AI-facing resources. Must use Schema.org DataCatalog format.

Required Fields

{
  "@context": "https://schema.org",
  "@type": "DataCatalog",
  "name": "string",
  "url": "string",
  "dataset": [
    {
      "@type": "Dataset",
      "name": "string",
      "url": "string"
    }
  ]
}

Recommended Per-Dataset Fields

• description
• dateModified
• encodingFormat

⭐ Karma Endpoint (/ai/karma.json)

The site's Digital Karma trust document. For strict v7.0 compliance this is a score-driven payload. A conceptual definition file is acceptable as a transitional state, but a scored payload is required for Certified, Pro, and Elite tier claims.

Scored Payload Fields

{
  "site": "string",
  "federation_version": "7.0",
  "digital_karma_score": 0.00-1.00,
  "badge": "Karma Certified|Karma Pro|Karma Elite",
  "signals": { ... },
  "updated_utc": "ISO8601"
}

🔗 Federation Endpoint (/ai/federation.json)

The formal federation relationship document, required in v7.0. Communicates your site's role in the network and its peer relationships.

Required Fields

• federation_version — "7.0"
• site — Canonical site URL
• role — Node type (e.g. hub, specialist, member)
• network — Network name
• peers — Array of related federation members

Peer Relationship Fields

• url — Peer canonical URL
• relationship — Type: peer, registry, parent, child, provider, consumer
• trust_level — Numeric or descriptive trust signal
• bidirectional — Boolean

📄 LLM Text File (/llm.txt)

Root-level plain-text summary of the site for language models. Lives at the site root, not in /ai/.

Should Include

• Site name and short description
• Canonical URL
• Core pages
• Available datasets
• AI endpoints list
• Federation context and version

Best Practices

• Markdown-style plain text, concise and scannable
• Use canonical absolute URLs for cross-site references
• No marketing copy — write for machines, not humans
• Update whenever key pages, endpoints, or positioning change

⭐ Digital Karma Scoring

Transparent, automated quality and trust scoring for AI websites. Score range: 0.00 to 1.00.

Scoring Formula

Signal Breakdown

Badge Thresholds

• ✅ Karma Certified: Score ≥ 0.70
• ⭐ Karma Pro: Score ≥ 0.85
• 🏆 Karma Elite: Score ≥ 0.95

Naming rule: Do not use Karma Bronze on v7.0 sites — it was renamed to Karma Certified in this version.

Read Full Scoring Spec →

🗺️ 4-Stage Federation Mapping New in v7.0

Advanced sites publish structured federation topology in a /federation/ folder. Recommended for Pro, required for Elite.

📦 Recommended Optional Files

Not required for minimum v7.0, but should be used whenever possible as the site matures.

Entity Files (/entities/)

Use /entities/ for explicit JSON-LD entity declarations. Required for Elite compliance.

• /entities/organization.jsonld
• /entities/brand.jsonld
• /entities/website.jsonld
• /entities/service.*.jsonld
• /entities/index.json — lists all entity files

✅ Implementation Checklist

Level 1: Starter — 🌐 Federation Member

• Create /ai/manifest.json with all required fields
• Create /ai/health.json with status and metrics
• Create /ai/catalog.json with at least one dataset
• Create /ai/karma.json (scored or conceptual)
• Create /ai/federation.json with network links
• Create /llm.txt at site root
• Set federation_version: "7.0" wherever the field appears
• Confirm HTTPS and a stable canonical domain
• Validate all JSON parses cleanly

Level 2: Certified — ✅ Karma Certified (Score ≥ 0.70)

• Achieve Digital Karma Score ≥ 0.70
• Add Schema.org Organization, WebSite, and WebPage markup on all primary pages
• Replace any Karma Bronze badge references with Karma Certified

Level 3: Pro — ⭐ Karma Pro (Score ≥ 0.85)

• Achieve Digital Karma Score ≥ 0.85
• Publish 2+ quality datasets with full Schema.org Dataset metadata
• Establish bidirectional federation peer links
• Deploy 4-stage federation mapping (/federation/ folder)

Level 4: Elite — 🏆 Karma Elite (Score ≥ 0.95)

• Achieve Digital Karma Score ≥ 0.95
• Implement self-maintaining automation (refreshed timestamps, topology, karma payload)
• Deploy /ai/diagnostics.json with zero open issues
• Publish /entities/ JSON-LD files with /entities/index.json
• Complete all 4 stages of federation mapping including v04_propagation.json
• Publish 5+ high-quality datasets

📁 Directory Blueprint

Minimum v7.0 Shape

/
├── ai/
│   ├── manifest.json
│   ├── health.json
│   ├── catalog.json
│   ├── karma.json
│   └── federation.json
├── llm.txt
├── robots.txt
└── datasets/           (optional but recommended)

Pro / Elite Shape

/
├── ai/
│   ├── manifest.json
│   ├── health.json
│   ├── catalog.json
│   ├── karma.json
│   ├── federation.json
│   ├── diagnostics.json
│   ├── sitemap.json
│   └── journal/
├── entities/
│   ├── index.json
│   ├── organization.jsonld
│   ├── brand.jsonld
│   ├── website.jsonld
│   └── service.*.jsonld
├── federation/
│   ├── index.json
│   ├── v01_listings.json
│   ├── v02_clusters.json
│   ├── v03_relationships.json
│   └── v04_propagation.json
├── datasets/
│   └── index.json
├── llm.txt
└── robots.txt

🔍 Validation Checklist

Before marking a site as v7.0 complete, verify all of the following:

• /ai/manifest.json loads and parses
• /ai/health.json loads and parses
• /ai/catalog.json loads and parses
• /ai/karma.json loads and parses
• /ai/federation.json loads and parses
• /llm.txt loads
• All JSON files are valid — no trailing commas, no unquoted keys
• Canonical URLs are absolute where referenced cross-site
• All timestamps use ISO 8601 UTC format
• federation_version is "7.0" everywhere it appears
• Schema.org markup exists on all primary pages
• Federation peer links are present and point to live endpoints
• robots.txt does not block intended AI discovery paths

🗂️ Legacy-Compatible Files

These files may still exist across portfolio sites and are allowed, but they do not replace the 6 required v7.0 artifacts. When modernizing a site, prioritize the required set first.