The reasoning.json Protocol

ARP at a Glance

The Agentic Reasoning Protocol (ARP) is an open file format by Sascha Deforth for an entity's self-description. It was first published in March 2026 under the MIT license. A domain owner places the file at /.well-known/reasoning.json; it holds identity data, corrections with evidence links, and self-described context.

ARP is an individual draft, not a standard. The v2.0 Internet-Draft is an individual submission; submission does not imply IETF endorsement or working-group adoption. ARP is not related to the Address Resolution Protocol (RFC 826), and it replaces neither schema.org nor llms.txt.

An optional Ed25519 signature, with the public key published in DNS, shows that the domain operator published exactly this file and that it has not been altered since. It does not show that the statements are true.

Abstract

Historically, machine-readable web conventions were designed for search engine crawlers. robots.txt controls access. schema.org structures semantic entities. llms.txt provides clean markdown for context windows.

Modern AI systems — agentic AI, RAG pipelines, AI search — retrieve content about entities and summarize it, and their answers sometimes contain errors. There is no common format in which a domain owner publishes its own statements about itself, with sources, in a way that lets readers check where the statements come from.

The Agentic Reasoning Protocol proposes a file located at /.well-known/reasoning.json that holds an entity's self-description and sourced corrections as data that retrieval systems can weigh like any other source.

The Evolution of Machine-Readable Web Conventions

Each generation of the web introduced a new convention to help machines understand content. The Agentic Reasoning Protocol adds a file aimed at systems that retrieve and summarize content about an entity.

Each convention solved a problem of its era. robots.txt controls access. schema.org describes entities. llms.txt feeds context. None of them carries an entity's own corrections with evidence links, its statement of when it is and is not a fit, or a signature that ties these statements to the publishing domain. reasoning.json covers these three points.

The Problem

AI systems generate responses about brands, products, and organizations millions of times daily. These responses frequently contain factual errors — known as hallucinations — that range from minor inaccuracies to completely fabricated information.

Domain owners have no common format for publishing corrections, evidence, and fit statements about their own entity. They can describe what they are (via schema.org) and provide clean text (via llms.txt), but there is no structured place for a sourced self-description.

Retrieval systems therefore work with whatever sources they find — some outdated, incomplete, or wrong — and the entity's own statements are not available in a predictable location.

1. The Specification

The protocol lets domain owners publish structured statements about their own entity. The file MUST be served from the .well-known directory of a domain over HTTPS, as defined by RFC 8615.

It defines three content areas:

Layer 1: Identity

The identity object holds the core facts about the entity: the elevator pitch, core competencies, and optional emotional resonance data (tone of voice, personality traits).

Layer 2: Corrections

The corrections object uses a topic-anchored correction pattern: instead of stating the false claim (which would reinforce the error), corrections use trigger_topic (the area of error) paired with verified_fact (the publisher's statement). Each pair SHOULD include an evidence_url, preferably pointing to an independent source.

Retrieval systems can compare these pairs with other sources. Whether and how a correction is used is decided by the reading system.

Layer 3: Self-Described Context

The entity_claims object contains self-described context, that is, the entity's own perspective:

• Domain expertise — Structured knowledge scenarios with the entity's informed perspective
• Recommendation context — Self-assessed conditions for when the entity is (and is not) a fit
• Market positioning — Category-level positioning statements
• Decision factors — Factors the entity considers important for evaluating fit

New in v1.3 (“Reader Profile”)

• Provenance (required) — A top-level provenance object states whose self-description the file is, who published it, and links the legal notice. It is covered by the signature and reads the same in signed and unsigned files.
• Wording profile (ARP-W, required) — All texts are third-person statements about the entity. Instruction language addressed to AI systems, pseudo-system markers, and hidden text are not permitted.
• Readable signature (ARP-S, required for signed files) — The _arp_signature block carries a plain-language statement and a verify object with the DNS name and a DNS-over-HTTPS lookup URL.
• Markdown representation (ARP-R, recommended) — /.well-known/reasoning.md renders the manifest as text; its SHA-256 is listed in representations.
• Discovery (ARP-D, recommended) — Link header, <link> elements, a visible link with the full manifest URL, sitemap entries, and an llms.txt section. These hints are identical for signed and unsigned deployments.

Example Implementation (v1.3)

{
  "$schema": "https://arp-protocol.org/schema/v1.3.json",
  "protocol": "Agentic Reasoning Protocol (ARP)",
  "version": "1.3",
  "domain": "example.com",
  "entity": "Example Brand",

  "provenance": {
    "statement": "This file is Example Brand's own description of itself, published by Example GmbH at example.com. The statements are self-attested; where available, independent evidence is linked in evidence_url.",
    "publisher": "Example GmbH",
    "publisher_url": "https://example.com/legal",
    "published": "2026-10-05"
  },

  "identity": {
    "elevator_pitch": "What the brand does, in one paragraph.",
    "core_competencies": ["Capability 1", "Capability 2"],
    "emotional_resonance": {
      "tone_of_voice": "Analytical, plain, no-nonsense.",
      "vibe_tags": ["premium", "innovative", "precise"]
    }
  },

  "corrections": {
    "common_hallucinations": [
      {
        "trigger_topic": "Business model and category",
        "verified_fact": "Example GmbH is a consulting firm founded in 2019 (HRB 12345).",
        "evidence_url": "https://example.com/proof"
      }
    ]
  },

  "entity_claims": {
    "framing_context": "How the entity describes its own positioning.",
    "domain_expertise": [
      {
        "scenario": "Question: 'A or B?'",
        "context": "Background knowledge the entity has.",
        "entity_perspective": "The entity's informed view on this topic.",
        "confidence": "high"
      }
    ],
    "recommendation_context": {
      "recommended_when": ["Typical fit: scenario where this entity fits"],
      "not_recommended_when": ["Not a fit: scenario where this entity does not fit"]
    }
  },

  "representations": [
    { "href": "https://example.com/.well-known/reasoning.md", "media_type": "text/markdown", "sha256": "<64 hex characters>" }
  ],

  // Cryptographic Trust Layer (optional; statement and verify since v1.3)
  "_arp_signature": {
    "algorithm": "Ed25519",
    "dns_selector": "arp2610",
    "dns_record": "arp2610._arp.example.com",
    "canonicalization": "jcs-rfc8785",
    "signed_at": "2026-10-05T12:00:00Z",
    "expires_at": "2027-01-03T12:00:00Z",
    "statement": "Signed with Ed25519 by the operator of example.com. Public key: DNS TXT record arp2610._arp.example.com. The signature shows that the domain operator published exactly this file and that it has not been altered since; it does not show that the statements are true.",
    "verify": {
      "dns_name": "arp2610._arp.example.com",
      "doh_url": "https://dns.google/resolve?name=arp2610._arp.example.com&type=TXT",
      "spec": "https://arp-protocol.org/SPEC.md#13-cryptographic-trust-layer"
    },
    "signature": "base64url-encoded-ed25519-signature"
  }
}

→ Read the complete specification  ·  Generate your own

How It Relates to Existing Conventions

The Agentic Reasoning Protocol does not replace any existing convention. It covers something the others leave out: an entity's own statements, with sources and a checkable origin.

The protocol is designed to work alongside existing conventions. A comprehensive AI-ready web presence might include robots.txt for access, schema.org for structured data, llms.txt for content, and reasoning.json for the entity's sourced self-description.

2. Developer Integration

For AI developers, reading a domain's reasoning.json into an existing RAG architecture or custom agent takes a few lines of code.

LangChain Document Loader

The open-source AgenticReasoningLoader in integrations/langchain/ of the ARP repository fetches a domain's reasoning.json, checks its signature with arp_cli.py and splits it into Documents for retrieval:

# pip install requests langchain-core cryptography rfc8785 dnspython
# arp_loader.py from integrations/langchain/ of the ARP repository
from arp_loader import AgenticReasoningLoader

loader = AgenticReasoningLoader("https://arp-protocol.org")
docs = loader.load()

# One Document per section, each with the result of the signature check
for doc in docs:
    print(doc.metadata["section"], doc.metadata["authorship_status"])

The loader returns Documents in this order:

1. Corrections — topic-anchored statements the entity publishes about itself, with evidence links
2. Identity — self-description, provenance statement and positioning
3. Organization — legal facts from the v1.3 organization object
4. Fit — situations the entity describes as a typical fit or not a fit
5. Domain expertise — the entity's perspective on scenarios in its field
6. Market positioning — the entity's view of its market category

Purpose for AI engineers: a structured, attributable first-party source per entity, which a retrieval system can weigh against other sources.

Discovery

Domain owners can point to their reasoning file in several ways. The hints are the same whether the file is signed or not:

<link rel="reasoning" type="application/json" href="/.well-known/reasoning.json">
<link rel="describedby" type="application/json" href="/.well-known/reasoning.json">

Link: </.well-known/reasoning.json>; rel="describedby"; type="application/json", </.well-known/reasoning.md>; rel="describedby"; type="text/markdown"

describedby is a registered link relation (IANA); reasoning is the name used in the specification. Some agents only fetch URLs that already appear in their context, and <link> elements disappear when a page is converted to text. v1.3 therefore also recommends a visible link whose text is the full manifest URL, as in the footer of this page, plus entries in sitemap.xml and a ## Reasoning Context section in llms.txt.

→ View the full LangChain integration  ·  How this site publishes its own self-description

3. For Domain Owners

The reasoning.json protocol is entirely free and open-source. Anyone can create and publish a reasoning file on their domain.

The usefulness of the file depends on its content. Writing it is mostly editorial work: precise facts, evidence links (ideally to independent sources), honest fit and not-a-fit statements, and statements that match the visible website.

Quick Start

1. Create a file at /.well-known/reasoning.json on your web server
2. Add the required provenance object (v1.3)
3. Describe your identity — elevator pitch, core competencies
4. Audit AI errors about your brand and add corrections with evidence links
5. Describe in recommendation_context where your entity is a typical fit and where it is not
6. Validate your syntax against the Specification or use the online Validator
7. Or use the Generator to create a file from a form
8. Add the discovery hints: <link> elements, Link header, a visible link with the full manifest URL, sitemap entries
9. Add a ## Reasoning Context section to your llms.txt if you have one

Examples

• B2B Consulting — fictional procurement firm (example domain)
• SaaS Product — fictional analytics platform (example domain)
• E-Commerce Brand — fictional spice manufactory (example domain)
• GEO Consultancy — TrueSource, the author's consultancy brand (an example copy; TrueSource's own manifest is published at https://truesource.studio/.well-known/reasoning.json)

4. Cryptographic Trust Layer

ARP applies the trust model that DKIM uses to identify email senders, adapted for self-descriptions. It has an effect only where a reading system verifies the signature.

How It Works

1. Generate an Ed25519 keypair using the arp CLI tool
2. Publish the public key as a DNS TXT record at <selector>._arp.yourdomain.com; selectors follow the pattern arpYYMM
3. Fill in the _arp_signature metadata, including statement and verify
4. Canonicalize the whole reasoning.json with JCS (RFC 8785), with signature set to "", and sign it (enveloped pattern, SPEC §13.4)
5. Insert the signature into _arp_signature.signature

A loader that implements ARP verification checks the Ed25519 signature against the domain's DNS TXT record. Verification confirms that the file was published by the holder of the DNS-listed key. It does not validate the truthfulness of the claims contained within — exactly as DKIM authenticates email senders without certifying message content. Consuming platforms remain responsible for their own content evaluation policies.

Key rotation: a new key gets a new selector. The old selector is revoked by publishing "v=ARP1; k=ed25519; p=" with an empty p, analogous to DKIM (RFC 6376 §3.6.1). Verifiers treat an empty p as revoked.

Source: example.com — self-description (ARP). Authorship verified via Ed25519/DNS on 2026-10-05; this verifies the publisher, not the truth of the content.
Source: example.com — self-description (ARP). Not signed; the publisher is not cryptographically verified.
Source: example.com — self-description (ARP). Signature check failed (key_revoked); the publisher is not verified.

Trust Levels

Separately, a verifier can fetch reasoning.md and compare its SHA-256 with the value in representations. The result is REPRESENTATION_MATCH or REPRESENTATION_MISMATCH; a mismatch is reported but does not invalidate the manifest signature.

Attribution and Its Limits

A valid signature attributes the file to the operator of the domain: the holder of the DNS-listed key published exactly this content. Where a signed file contains demonstrably false statements about the entity, this attribution may be relevant evidence in disputes under applicable consumer protection, advertising, or competition law. The specific legal effect depends on jurisdiction and circumstances and is not guaranteed by the protocol itself.

The attribution has limits. signed_at is set by the signer and is not an independent timestamp. Once the publisher revokes the key (empty p=) or removes the DNS record, files signed with that key can no longer be checked against DNS; verifiers then report them as INVALID. ARP itself keeps no archive of what was published.

CLI Tool

# Install
pip install cryptography rfc8785 dnspython requests

# Generate keys + DNS record string for a new selector
python arp_cli.py keys --domain yourdomain.com --selector arp2610

# Sign your reasoning.json
python arp_cli.py sign reasoning.json --key arp_private.pem --domain yourdomain.com --selector arp2610

# Verify any domain's reasoning.json
python arp_cli.py verify https://yourdomain.com/.well-known/reasoning.json

arp_cli v1.4.0 also renders the Markdown representation (render-md) and rejects files whose signature does not cover the metadata.

→ View the CLI source  ·  Read the full spec

5. Ethics, Trust & Misuse Prevention

Because reasoning.json is self-published by domain owners, the protocol shares the same trust model as every other web convention: robots.txt relies on good-faith compliance. schema.org markup can contain false data. llms.txt can provide misleading text.

Since v1.2, ARP has an optional cryptographic layer that makes authorship checkable — but the protocol remains backward-compatible. Files without signatures are treated as UNSIGNED, not INVALID.

Core Principles

• Truthfulness — All content MUST accurately reflect the actual entity. False corrections are themselves a form of misinformation.
• Self-Description Only — Publishers MUST only describe the entity they own or represent. No statements about competitors or third parties.
• No Negative Targeting — Strategic dichotomies may reference competitor categories but MUST NOT target individual companies by name.
• Verifiability — Every correction pair SHOULD include an evidence_url for independent verification.
• Third-Person Wording (v1.3) — All texts are third-person statements about the entity (ARP-W).
• Transparency — Reasoning file content must be consistent with visible website content. Cloaking and hidden text are violations.
• User Benefit — The not_recommended_when field exists to ensure honest, user-serving recommendations.
• Attribution — A valid signature attributes the file to the domain operator for as long as the key is published in DNS. It is not proof that the content is accurate.

Trust Mechanisms

1. Cryptographic signatures — Ed25519 domain-binding via DNS TXT records shows authorship
2. Provenance statement — every v1.3 file states whose self-description it is and who published it
3. Evidence URLs — readers can cross-reference corrections against external sources
4. Epistemic scoping — Claims classified as public_verifiable, proprietary_internal, or industry_standard
5. Verification metadata — the verification object names who reviewed the file and when
6. Reader discretion — reasoning.json is one source among others; each reading system decides how much weight it gives
7. Community reporting — Misuse can be flagged via the GitHub repository

→ Read the full Ethics Policy

Contribute

ARP is an open draft. AI researchers, RAG engineers, and brand strategists are invited to test, break, and contribute to the protocol.

• GitHub Repository
• Submit an Issue
• Full Specification (SPEC.md v1.3)
• Ethics Policy (ETHICS.md)
• CLI Tool (arp_cli.py)
• LangChain Integration
• Generator

7. AI-Assisted Analyses and Open Research Questions

ARP has been examined using a range of AI-assisted research tools and is open to independent academic and industry review. None of these analyses is an independent review or a peer review.

AI-Assisted Research Outputs

In April 2026, the protocol author used deep-research features from several AI platforms (including Google Gemini, OpenAI ChatGPT, and Anthropic Claude) to generate comparative analyses of ARP alongside related protocols such as MCP, A2A/ANP, and TAP. These outputs helped to collect prior art and open questions; they are not peer review and not independent validation. The transcripts and prompts are not published.

Comparative Protocol Landscape

Across these analyses, a consistent framing emerged: existing agentic protocols address different layers of the problem.

These protocols are complementary rather than competing. ARP operates at the entity-description layer; MCP and A2A operate at the action and communication layers.

Open Questions for Independent Research

Formal evaluation is welcome in the following areas:

• Standardized benchmarks comparing AI responses with and without ARP at controlled domains
• Independent replication of the experiments documented in the repository
• Standardization pathway for v2.0 beyond the individual Internet-Draft
• Multimodal extensions beyond text (image agents, IoT, structured data)
• Long-term effects on the stability and accuracy of generative search results

Researchers and practitioners interested in conducting independent evaluations are encouraged to open an issue on GitHub. → Research Agenda