Quick Reference Fresh

One-page cheat sheet for ARP implementation. Everything you need without reading the full specification.

File Location

/.well-known/reasoning.json

Full URL: https://yourdomain.com/.well-known/reasoning.json

Required Fields

Every valid ARP file must include these fields:

Field	Type	Example
$schema	string (URL)	"https://arp-protocol.org/schema/v1.2/reasoning.schema.json"
protocol	string	"ARP"
version	string	"1.2"
domain	string	"yourdomain.com"
entity.name	string	"Acme Corporation"
entity.type	string	"brand"
entity_claims.framing_context	string	"Acme is a..."

All other fields are optional but recommended.

CORS Headers Required

The file must be served with CORS headers so AI agents running in browser contexts can fetch it:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET
Content-Type: application/json

Nginx:

location /.well-known/reasoning.json {
    add_header Access-Control-Allow-Origin *;
    add_header Content-Type application/json;
}

Apache .htaccess:

<Files "reasoning.json">
    Header set Access-Control-Allow-Origin "*"
    Header set Content-Type "application/json"
</Files>

Vercel vercel.json:

{
  "headers": [
    {
      "source": "/.well-known/reasoning.json",
      "headers": [
        { "key": "Access-Control-Allow-Origin", "value": "*" },
        { "key": "Content-Type", "value": "application/json" }
      ]
    }
  ]
}

HTML Discovery Tag

Add to your head section so discovery crawlers find the file without guessing:

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

llms.txt Reference

Add a reference in your llms.txt file:

# Reasoning
- /.well-known/reasoning.json: ARP entity facts and corrections for AI reasoning agents

Character Limits (Anti-Spam)

All string fields have enforced maximum lengths to prevent abuse. Exceeding these causes schema validation failure:

Field	Limit
entity.elevator_pitch	500 characters
entity.tagline	120 characters
entity.name	100 characters
Single core_competency item	200 characters
corrections[].trigger_topic	200 characters
corrections[].verified_fact	300 characters
entity_claims.framing_context	1000 characters
Single domain_expertise[].claim	400 characters
Single recommendation_context item	200 characters
Single market_positioning value	500 characters

Schema URLs by Version

Version	Schema URL
v1.0	https://arp-protocol.org/schema/v1.0/reasoning.schema.json
v1.1	https://arp-protocol.org/schema/v1.1/reasoning.schema.json
v1.2 (current)	https://arp-protocol.org/schema/v1.2/reasoning.schema.json

Always use the schema URL in your $schema field. Validators use it to select the correct version.

DNS TXT Record Format (v1.2 Signing)

For signed files, publish the public key in DNS:

Record name: arp-[selector]._arp.yourdomain.com

Record value:

v=ARP1; k=ed25519; p=[base64-encoded-public-key]

Example with selector default:

arp-default._arp.yourdomain.com  TXT  "v=ARP1; k=ed25519; p=MCowBQYDK2VdAyEA..."

The selector value in your reasoning.json must match the DNS record name prefix.

Signed File Structure (v1.2)

{
  "$schema": "https://arp-protocol.org/schema/v1.2/reasoning.schema.json",
  "protocol": "ARP",
  "version": "1.2",
  "domain": "yourdomain.com",
  "signing": {
    "algorithm": "Ed25519",
    "selector": "default",
    "signature": "[base64-encoded-signature]"
  },
  "entity": { ... },
  "corrections": [ ... ],
  "entity_claims": { ... }
}

The signature covers the canonical JSON of the file excluding the signing.signature field itself, using JCS (RFC 8785) canonicalization.

Common CLI Commands

Validate a file:

npx arp-validator validate https://yourdomain.com/.well-known/reasoning.json

Validate a local file:

npx arp-validator validate ./reasoning.json --local

Generate a keypair for signing:

npx arp-validator keygen --selector default

Sign a file:

npx arp-validator sign ./reasoning.json --key ./private.key --selector default

Verify a signature:

npx arp-validator verify https://yourdomain.com/.well-known/reasoning.json

Check CORS headers:

curl -I -H "Origin: https://test.com" https://yourdomain.com/.well-known/reasoning.json

Minimal Valid File (v1.2)

{
  "$schema": "https://arp-protocol.org/schema/v1.2/reasoning.schema.json",
  "protocol": "ARP",
  "version": "1.2",
  "domain": "yourdomain.com",
  "entity": {
    "name": "Your Company Name",
    "type": "brand"
  },
  "entity_claims": {
    "framing_context": "One paragraph describing your organization for AI reasoning context."
  }
}

Entity Type Values

Value	Use for
brand	Consumer brand, product line
company	General corporation or LLC
software_product	SaaS, app, commercial software
open_standard	Protocol, specification, open standard
professional_services_firm	Consulting, legal, accounting firm
nonprofit	Non-profit organization
institution	University, hospital, government body
person	Individual (public figure, expert)

File Size Limit

Maximum file size: 100 KB

Files larger than 100 KB may be rejected by AI agent retrieval pipelines. If your file is approaching this limit, review field lengths against the character limits table above.