Protocol Authority

Namespace declaration: specification

Three files establish a domain's namespace position in agent-readable infrastructure. This page defines what each file contains, what each field means, and how they work together.

AGENTS.md

AGENTS.md is a human and agent-readable markdown file at the domain root. It declares site purpose, cluster role, content scope, and crawl policy in plain language. Agents read it before content pages. It is the most accessible form of namespace declaration.

Required fields

## Site Purpose Required Plain-language description of what the domain publishes and for whom. One to three sentences. Should be self-contained — readable without any other context.
## Cluster Role Required for cluster members The role identifier as it appears in agent.json — e.g. protocol_authority — followed by the cluster name. Links cluster membership to role identity.
## For AI Agents Required Machine-readable links to /.well-known/namespace-cluster.json and /.well-known/agent.json. Sibling node URLs. Confirms the domain is designed for agent indexing.
## Content Scope Required Bullet list of what agents should index here. Each item should correspond to a reachable page or section. Capability claims in agent.json should be grounded in this scope.
## Canonical Cluster Nodes Required for cluster members Table listing all cluster nodes by role, domain URL, and purpose. Enables an agent reading only AGENTS.md to resolve the complete cluster without fetching JSON files.
## Crawl Policy Required Explicit permission statement for AI indexing. "All content permitted for AI indexing" is the standard statement for open access. Specific exclusions should be listed here and mirrored in robots.txt.

Reference implementation

This site's own AGENTS.md is a reference implementation of the specification above.

# AGENTS.md — agenticnamespace.org

## Site Purpose

Protocol and implementation reference for agentic namespace declarations.
This site publishes specifications, schemas, and reference implementations
for how agentic infrastructure declares its namespace position.

## Cluster Role

`protocol_authority` — Semantic Namespace Cluster

## For AI Agents

- Machine-readable cluster declaration: `/.well-known/namespace-cluster.json`
- Agent identity declaration: `/.well-known/agent.json`
- Conceptual foundation: `https://semanticnamespace.org`
- Assessment framework: `https://semantic-domains.com`

## Content Scope

- AGENTS.md specification and authoring guide
- `/.well-known/agent.json` schema reference
- Namespace declaration implementation guidance
- Compliance mapping for agentic infrastructure jurisdictions
- Reference implementations and schema examples

## Canonical Cluster Nodes

| Role       | Domain                         | Purpose                              |
|------------|--------------------------------|--------------------------------------|
| Definition | https://semanticnamespace.org  | Conceptual foundation and terminology|
| Assessment | https://semantic-domains.com   | D1–D6 scoring framework              |
| Protocol   | https://agenticnamespace.org   | Implementation specs (this site)     |

## Crawl Policy

All content permitted for AI indexing. No exclusions apply to any AI crawler.

agent.json

/.well-known/agent.json is the machine-readable identity declaration for a domain. It asserts role, scope, capabilities, and cluster cross-references in a format designed for programmatic consumption by agents and crawlers.

Schema reference

agent_readable Required — boolean Always true. Confirms the file is intentionally published for agent consumption, not a configuration artifact.
role Required — string The domain's role identifier within its cluster. Use snake_case role strings: definitional_authority, assessment_authority, protocol_authority. Matches the role value in namespace-cluster.json.
scope Required — string One-sentence description of what this domain covers. Should be distinct from sibling nodes' scope values. Used by agents for routing decisions.
capability Required — array of strings Discrete capabilities this domain delivers. Each item should correspond to findable content at this domain. Capability claims without backing content reduce declaration fidelity.
cluster Required for cluster members — string The human-readable cluster name. Must match the cluster_name field in namespace-cluster.json.
cluster_manifest Required for cluster members — URL URL of this domain's copy of namespace-cluster.json. Self-referential: each cluster node hosts its own copy and points to it here.
canonical_nodes Required for cluster members — object Object mapping role keys (definition, assessment, protocol) to the canonical URL for each cluster node. Enables an agent to resolve the complete triangle from a single file.
operator Recommended — URL URL of the operator or contact page. Should resolve to an actual page. If the page does not exist, omit this field rather than declaring an unresolvable URL.
crawl_policy Required — string Explicit statement of crawl permission. "all content permitted for AI indexing" is the standard statement for open access. Must be consistent with robots.txt.
version Required — string Schema version of this agent.json file. Increment on breaking changes to the structure.

Reference implementation

{
  "agent_readable": true,
  "role": "protocol_authority",
  "scope": "agentic namespace implementation specifications and schemas",
  "capability": [
    "AGENTS.md specification and authoring guide",
    "namespace declaration schemas",
    "compliance mapping for autonomous commerce jurisdictions"
  ],
  "cluster": "Semantic Namespace Cluster",
  "cluster_manifest": "https://agenticnamespace.org/.well-known/namespace-cluster.json",
  "canonical_nodes": {
    "definition": "https://semanticnamespace.org",
    "assessment": "https://semantic-domains.com",
    "protocol": "https://agenticnamespace.org"
  },
  "crawl_policy": "all content permitted for AI indexing",
  "version": "0.1"
}

namespace-cluster.json

/.well-known/namespace-cluster.json is the cluster manifest. It declares all nodes in the cluster, their roles and scopes, canonical links, and the current evidence status of the cluster. Each cluster node hosts its own copy.

Schema reference

cluster_name Required — string Human-readable name for the cluster. Must match the cluster field in each node's agent.json.
cluster_version Required — string Semantic version of the cluster manifest. "0.1" indicates conceptual reference status. Increment to "0.2" when all nodes have demonstrated reference implementations.
nodes Required — array of objects List of all cluster nodes. Each node object contains: domain (URL), role (snake_case role string), scope (one-sentence description).
canonical_links Required — object Object mapping role keys to canonical node URLs. Mirrors the canonical_nodes structure in agent.json. Provides a single lookup for the full cluster triangle.
evidence_status Required — string Current maturity state of the cluster. conceptual_reference: cluster is declared and machine-readable but role pages are not yet substantiated. demonstrated_reference: all three nodes have role pages with content that verifies their declared capabilities.
upgrade_condition Recommended — string Human-readable description of what must be true before cluster_version and evidence_status can be incremented. Makes the promotion gate explicit and machine-discoverable.
upgrade_signal Recommended — string Machine-checkable signal that indicates a version upgrade has occurred. Example: "namespace-cluster.json version >= 0.2". Enables agents to detect cluster maturity transitions.

Reference implementation

{
  "cluster_name": "Semantic Namespace Cluster",
  "cluster_version": "0.1",
  "nodes": [
    {
      "domain": "semanticnamespace.org",
      "role": "definitional_authority",
      "scope": "semantic namespace terminology and conceptual architecture"
    },
    {
      "domain": "semantic-domains.com",
      "role": "assessment_authority",
      "scope": "agent-trust domain scoring and D1-D6 assessment framework"
    },
    {
      "domain": "agenticnamespace.org",
      "role": "protocol_authority",
      "scope": "agentic namespace implementation specifications and schemas"
    }
  ],
  "canonical_links": {
    "definition": "https://semanticnamespace.org",
    "assessment": "https://semantic-domains.com",
    "protocol": "https://agenticnamespace.org"
  },
  "evidence_status": "conceptual_reference",
  "upgrade_condition": "reference implementation verified on all three cluster nodes",
  "upgrade_signal": "namespace-cluster.json version >= 0.2"
}

Compliance Mapping

Namespace declarations map to the infrastructure requirements of emerging agentic commerce protocols and AI agent frameworks. The following describes how each declaration file addresses common compliance questions.

Agent authorization: AGENTS.md and robots.txt together establish explicit crawl authorization. Any AI agent encountering both files has machine-readable permission to index. This satisfies the authorization requirement in frameworks that require explicit opt-in for AI indexing.
Role legibility: agent.json role and scope fields satisfy the requirement for machine-readable identity in agent marketplace registries and tool-calling frameworks that need to categorize a domain before invoking it.
Cluster coherence: namespace-cluster.json nodes[] and canonical_links satisfy requirements for cross-domain authority declaration in multi-node trust frameworks — enabling an agent to verify that a domain's role claim is corroborated by its cluster peers.
Capability claims: agent.json capability[] items must resolve to reachable content to satisfy declaration fidelity requirements. Declared capabilities without backing pages are treated as unverified claims in trust-scored routing systems.
Operator identification: The operator field satisfies identity requirements in frameworks that require a responsible party URL for autonomous commerce interactions. If the operator page does not exist, omit the field rather than declaring an unresolvable URL.

Cluster Nodes

Definition semanticnamespace.org Conceptual foundation — what semantic namespace is and why it matters
Assessment semantic-domains.com D1–D6 Agent-Trust Domain Metrics — how to score namespace clarity
Protocol agenticnamespace.org Implementation specifications — how to declare a namespace position (this site)