Validating Your reasoning.json

Fresh

A valid reasoning.json file is one that conforms to the ARP JSON Schema, passes all field-level constraints, and is correctly served with the required HTTP headers. This SOP covers all three validation methods.

Validation Methods

Method 1 - Web Validator (Fastest)

The ARP web validator accepts either a raw JSON paste or a public URL to fetch and validate. It provides:

• JSON syntax check
• Schema compliance check
• Field-level constraint validation (character limits, array sizes)
• Layer completeness scoring (identity, corrections, entity_claims)
• Anti-spam limit checks
• Cryptographic trust layer validation (v1.2)
• Version-specific migration guidance

To use: navigate to the validator, paste your JSON or enter your domain URL, and run the validation.

Method 2 - JSON Schema Validation (Programmatic)

The ARP JSON Schema can be used with any JSON Schema validator (ajv, jsonschema, etc.) for automated validation in CI pipelines.

// Using ajv (npm install ajv ajv-formats)
const Ajv = require('ajv').default;
const addFormats = require('ajv-formats');
const schema = require('./arp-schema-v1.2.json');
const reasoningJson = require('./reasoning.json');

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

const validate = ajv.compile(schema);
const valid = validate(reasoningJson);

if (!valid) {
  console.error('Validation errors:', validate.errors);
  process.exit(1);
}

console.log('reasoning.json is valid');

# Using jsonschema (pip install jsonschema)
import json
import jsonschema

with open('reasoning.json') as f:
    reasoning = json.load(f)

with open('arp-schema-v1.2.json') as f:
    schema = json.load(f)

try:
    jsonschema.validate(reasoning, schema)
    print('reasoning.json is valid')
except jsonschema.ValidationError as e:
    print(f'Validation error: {e.message}')
    exit(1)

Method 3 - Editor Integration

Add the $schema field to your reasoning.json and any JSON-aware editor (VS Code, IntelliJ, WebStorm) will use the schema for inline validation, autocomplete, and hover documentation:

{
  "$schema": "https://agentic-reasoning-protocol.com/schemas/reasoning-v1.2.json",
  ...
}

Validation Checks Performed

The validator runs checks across seven layers:

Layer 1 - JSON Syntax

• File parses as valid JSON (RFC 8259)
• UTF-8 encoding
• No trailing commas, no comments (standard JSON restrictions)

Layer 2 - Schema Compliance

• All required fields present (protocol, version, domain, entity, entity_claims)
• protocol field exactly equals "Agentic Reasoning Protocol (ARP)"
• version is a valid semver string
• domain is a valid FQDN
• Field types match schema definitions

Layer 3 - Identity Layer Completeness

• elevator_pitch present (recommended)
• core_competencies has at least one entry (recommended)
• Character limits respected: tagline (120), elevator_pitch (500), headquarters (100), etc.
• not_to_be_confused_with max 5 entries

Layer 4 - Anti-Hallucination Layer

• corrections.common_hallucinations max 20 entries
• Each entry has trigger_topic (required, max 200 chars) and verified_fact (required, max 300 chars)
• No deprecated false_claim field present (v1.0 pattern - will warn)
• epistemic_scope values are valid enum members if present

Layer 5 - Entity Claims Presence

• entity_claims.framing_context present (required)
• domain_expertise max 10 entries, each within character limits
• recommendation_context.recommended_when max 10 entries
• recommendation_context.not_recommended_when max 10 entries
• market_positioning values max 200 chars each

Layer 6 - Anti-Spam Limits

Character limit enforcement across all fields prevents reasoning.json from being used to inject arbitrarily large amounts of text into AI contexts. The validator checks every field against its defined limit and flags violations.

Total file size check: the complete JSON including all sections must be under 100KB.

Layer 7 - Cryptographic Trust Layer (v1.2)

If _arp_signature is present:

• All required signature fields present (algorithm, publicKey, signature, signedAt, canonicalization, dns_selector)
• algorithm is "Ed25519"
• canonicalization is "JCS-RFC8785"
• signedAt is a valid ISO 8601 timestamp
• DNS query performed for `{dns_selector}._arp.{domain}` TXT record
• DNS record parsed and public key extracted
• Signature verified against canonical JSON bytes (excluding _arp_signature)

Validation Checklist

Use this checklist before deploying your file:

Required fields:

• [ ] protocol equals exactly "Agentic Reasoning Protocol (ARP)"
• [ ] version is a valid semver string
• [ ] domain matches the domain where the file is hosted
• [ ] entity is present and under 200 chars
• [ ] entity_claims.framing_context is present

Recommended fields:

• [ ] identity.elevator_pitch is present and concrete (not marketing language)
• [ ] identity.core_competencies has at least 2-3 entries
• [ ] corrections.common_hallucinations has entries for your most common AI errors
• [ ] entity_claims.recommendation_context.not_recommended_when is populated (builds trust)

HTTP headers:

• [ ] Content-Type: application/json is set
• [ ] Access-Control-Allow-Origin: * is set
• [ ] File is accessible at /.well-known/reasoning.json
• [ ] File returns HTTP 200 (not 301, 302, or 404)

v1.2 signing (if applicable):

• [ ] _arp_signature block is present and complete
• [ ] DNS TXT record is published at `{selector}._arp.{domain}`
• [ ] DNS record value matches format v=arp1; k=ed25519; p={base64}
• [ ] Signature verifies against canonical bytes
• [ ] Private key is stored securely, not in the codebase

Version Migration Guidance

v1.0 to v1.1

The primary change is the anti-hallucination correction format. The validator will warn on false_claim / correction_fact pairs and suggest converting to trigger_topic / verified_fact.

Before (v1.0):

{
  "false_claim": "Founded in 2015",
  "correction_fact": "Founded in 2021"
}

After (v1.1+):

{
  "trigger_topic": "company founding year",
  "verified_fact": "Founded in 2021 by Jane Smith and Marcus Chen."
}

v1.1 to v1.2

v1.2 adds optional _arp_signature and diagnostics blocks. Existing v1.1 files are valid v1.2 files with these blocks omitted. To upgrade to full v1.2 with cryptographic signing, follow the Cryptographic Signing SOP.

Update your version field from "1.1.0" to "1.2.0" after adding any v1.2 features.