Agent-Facts Protocol — v2.2 (Normative)

Last updated: 2026-03-02 at 14:30 UTC

Scope

This document specifies normative, additive changes to the Agent-Facts.html protocol (v2.2). Heavy infrastructure changes (cryptographic signatures, JSON-only canonical migration, multi-authority trust) are deferred to v3.0.

1. Core Required Fields (Normative)

Every Agent-Facts page/document MUST expose these visible and machine-readable fields (in JSON-LD or mirrored machine-readable output):

• protocol_version — string, semantic version (e.g., "2.2")
• entity_legal_name — string
• primary_url — string, absolute URL
• last_modified_iso8601 — string, RFC3339 / ISO8601 UTC timestamp (e.g., 2026-03-02T14:30:00Z)
• jurisdiction — string (country or governing jurisdiction)
• primary_contact — object with at least one contact method (e.g., email)

Missing any required field MUST cause validation to fail with a diagnostic code. Implementations MAY accept pages missing these fields for legacy reasons, but such pages are non-compliant with v2.2.

2. Timestamp Precision & Parity (Normative)

Format: `last_modified_iso8601` MUST use RFC3339/ISO8601 with the UTC timezone suffix (`Z`) and include second precision.

Parity: If the server provides an HTTP `Last-Modified` header, it MUST match the HTML/JSON `last_modified_iso8601` value to second precision. Consumers SHOULD treat payloads as stale if these values diverge.

3. Claim Provenance Labels (Normative)

Each machine-readable claim SHOULD include these provenance properties:

• claim_id — stable identifier for the claim
• claim_text — the textual claim
• source_type — one of `official_record`, `first_party`, `third_party`, `self_asserted`
• source_url — optional URL to evidence
• evidence_date — optional ISO8601 date of evidence

Claims with `self_asserted` MUST be labeled as such in both visible text and machine-readable output.

4. Cross-file Consistency (Normative)

`protocol_version` and `last_modified_iso8601` MUST match across the canonical Agent-Facts page, the `llms.txt` entry, and any spec metadata endpoints. If values differ, consumers MUST treat the newest RFC3339 timestamp as authoritative and log the discrepancy.

5. Anti-Spam & Claim Quality Rules (Normative)

Machine-readable fact blocks MUST NOT contain unverifiable superlatives, promotional ranking claims (e.g., "#1", "best"), or affiliation assertions without a `source_type=third_party` and a resolvable `source_url`. Marketing copy must remain outside core machine-readable sections.

6. Operational Guidance (Recommended)

• Discovery: Include an `Agent-Facts:` directive in `robots.txt` pointing to the canonical page (optional, recommended): Agent-Facts: https://agent-facts.com/agent-facts.html. Hosting a non-mandatory `/.well-known/agent-facts.json` is permitted as an additional entry point.
• Payload size: Keep the machine-readable core under 64 KB uncompressed where practical. Consumers may impose stricter limits.
• SSRF mitigation: Consumers MUST not fetch sub-resources that resolve to private IP ranges (RFC1918/3927).
• Validation: Implement JSON-LD mirroring checks to ensure visible text and machine-readable JSON-LD are identical for core facts.

7. Testing & Acceptance

Implementors should validate pages using the following tests:

1. Core Fields Test — Ensure all required fields are present and properly formatted.
2. Timestamp Test — Verify ISO8601 `Z` suffix and parity with HTTP `Last-Modified`.
3. Provenance Test — Confirm claims include `source_type` and that `self_asserted` labels appear visibly.
4. Cross-file Consistency — Confirm `protocol_version` and `last_modified_iso8601` match across artifacts.
5. Anti-spam Lint — Flag promotional language in machine-readable fields without third-party evidence.

8. Upgrade & Compatibility Notes

v2.2 is intentionally additive. Implementations supporting v2.1 will continue to serve content; however, v2.2-compliant sites should adopt the normative fields and timestamp rules. Major, breaking changes (cryptographic signatures, JSON-first canonicalization, multi-authority trust/revocation) are reserved for v3.0.

For implementation examples and a machine-readable schema appendix, consult the project repository.