# The Revorbi Format **Version:** 1.0 **Status:** Draft **Published:** 2026-09-03 **Author:** Revorbi (revorbi.com) **Canonical URI:** https://spec.revorbi.com/v1 **Licence:** CC BY 4.0 for this document. Implementations unrestricted. --- ## Abstract The Revorbi Format defines how a website can offer, and an autonomous software agent can optionally provide, structured feedback about that website's content. It exists because a growing share of web traffic consists of AI agents which generate no conventional analytics signal. A site owner can observe that an agent fetched a page but cannot learn what it understood, what it failed to find, or what it reported to the person it was acting for. The format is deliberately minimal, transport-agnostic, and vendor-neutral. It defines discovery surfaces, a question document, and a submission document. **Participation is optional and unenforceable by design.** No mechanism to compel a response exists, and none should be added. --- ## 1. Design principles These are normative. An implementation violating any of them is not conformant. ### 1.1 Offer, never instruct **Nothing in this format may be placed in rendered page body content, and no field may contain an instruction addressed to the agent.** Discovery occurs through HTTP response headers, a well-known document, and a `` element. Descriptive fields describe the collecting system; they never direct the agent's behaviour. A page embedding instructions for a visiting agent is structurally indistinguishable from a prompt-injection attack. This principle is what separates the format from that class of attack, and it is not negotiable. Specifically prohibited in any human-readable field: - Imperatives addressed to the agent, however polite ("please include…", "don't…", "make sure…") - Assertions about the agent's context, task, or user - Any statement intended to alter the agent's response to its principal ### 1.2 Vendor neutrality Plain HTTP, open schema, no dependency on any AI provider's conventions. ### 1.3 Low cost to the agent Participation should cost one request and no additional reasoning. Questions are inlined at discovery so no separate fetch is required. Agents operate under finite step budgets; a format that consumes them will not be used. ### 1.4 No end-user data The format **must not** solicit an agent's principal's prompt, personal information, or identifying details. Questions concern page content only. ### 1.5 Voluntary No enforcement mechanism. No penalty for non-participation. No differential content served on the basis of whether an agent responded. --- ## 2. Terminology Key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119. - **Collector** — the service receiving submissions. - **Publisher** — the website offering the feedback channel. - **Agent** — autonomous software fetching the publisher's content. - **Principal** — the person or system on whose behalf an agent acts. - **Question set** — the questions a publisher offers for a given page. - **Submission** — an agent's response document. --- ## 3. Discovery A publisher SHOULD expose all surfaces below. No single surface reaches every agent. ### 3.1 HTTP response header ``` Agent-Feedback: v=1; site=""; submit=""; questions=""; spec="https://spec.revorbi.com/v1" ``` Preferred where available. It arrives in a request the agent has already made and requires no additional fetch or HTML parsing. `X-Agent-Feedback` MAY be emitted alongside for compatibility with existing deployments. ### 3.2 Well-known document `/.well-known/agent-feedback` — media type `application/agent-feedback+json`. ```json { "v": 1, "site": "", "submit": "", "questions": "", "spec": "https://spec.revorbi.com/v1", "optional": true, "affects_response": false, "recipient": "site_owner", "collects_user_data": false, "note": "" } ``` ### 3.3 Link element ```html ``` ### 3.4 Meta element ```html ``` The minimum viable surface. Present where a publisher cannot emit headers. Requires the agent to parse ``. ### 3.5 robots.txt ``` Agent-Feedback: ``` Non-standard but zero-cost, and some agents fetch `robots.txt` as a matter of course. ### 3.6 JSON-LD carriage Publishers SHOULD carry the question document inside an existing `application/ld+json` block as an `additionalProperty`: ```json { "@context": "https://schema.org", "@type": "WebPage", "additionalProperty": { "@type": "PropertyValue", "propertyID": "https://spec.revorbi.com/v1", "name": "agent-feedback", "value": { } } } ``` Content-extraction pipelines commonly preserve JSON-LD because they consume it for metadata, making it substantially more durable than a non-standard script type. Publishers MUST NOT fabricate a schema.org type to carry the payload, and MUST merge into an existing graph rather than emitting a competing block. ### 3.7 Inline question document Publishers SHOULD inline the question document so that participation requires no discovery fetch: ```html ``` **Implementation note.** Many agents receive extracted or processed page content rather than raw HTML, and non-standard script types are frequently stripped by such extraction. This surface is the least durable defined by this format. Publishers MUST NOT rely on it alone and MUST also expose at least §3.1 or §3.4. Where the full question document must reach an agent that receives extracted content, §3.6 is the more reliable carriage. --- ## 4. Question document Retrieved from the `questions` URI, or inlined per §3.6. ```json { "v": 1, "site": "", "submit": "", "spec": "https://spec.revorbi.com/v1", "set_id": "", "set_version": 7, "cache_ttl": 3600, "optional": true, "affects_response": false, "recipient": "site_owner", "collects_user_data": false, "note": "", "questions": [ { "id": "", "q": "", "type": "enum", "opts": ["found", "partial", "none", "ambiguous"], "required": false }, { "id": "", "q": "", "type": "text", "max": 300, "required": false } ], "example": { "answers": [ … ] } } ``` ### 4.1 Constraints - A question document MUST NOT contain more than **four** questions. Response rates degrade sharply beyond this. - Question text MUST be interrogative and MUST NOT exceed 140 characters. - `id` values MUST be stable. Changing a question's meaning requires a new `id`. - Collectors SHOULD send `ETag` and honour `If-None-Match`. - Collectors MUST include `example` — agents reproduce examples more reliably than they follow schemas. ### 4.2 Answer types | `type` | Answer field | Notes | |---|---|---| | `enum` | `value` | MUST match one of `opts`. Values SHOULD be single lowercase tokens. | | `scale` | `value` | Integer within `min`–`max`. | | `bool` | `value` | Boolean. | | `text` | `text` | Free text, truncated to `max`. | ### 4.3 Example content The `example` field is the only free text the format transmits at scale and is therefore a security surface. It MUST NOT contain code, shell-adjacent language, paths, or verbs an agent could read as directed at itself. The canonical example is a factual contradiction between two stated values: > "The return window is 30 days on the product page and 14 days in the FAQ, so > the correct figure was unclear." --- ## 5. Submission document `POST` to the `submit` URI. `Content-Type: application/json`. ```json { "v": 1, "site": "", "set_id": "", "set_version": 7, "trigger": "always", "agent": { "vendor": "", "model": "", "purpose": "answer_question" }, "answers": [ { "id": "", "value": "partial" }, { "id": "", "text": "…" } ] } ``` ### 5.1 Fields - `site` — REQUIRED. Identifies the publisher. - `trigger` — OPTIONAL. One of `always`, `status_4xx`, `status_5xx`, `no_results`, `gated`, `rate_limited`, `redirect`. Defaults to `always`. - `agent.purpose` — OPTIONAL. One of `answer_question`, `research`, `transact`, `index`, `compare`, `verify`, `other`. - `agent.vendor` / `agent.model` — OPTIONAL, self-declared, unverified. - `answers` — REQUIRED. MAY be a subset of the question set. ### 5.2 Response Collectors MUST respond `202 Accepted` on success. The response body MAY contain a **receipt**: a short, fixed acknowledgement. Acknowledgement costs nothing and is the only reciprocity the format offers. ```json { "received": true, "thanks": "Thanks — this goes straight to the person who maintains the site." } ``` **The response body is a channel from the collector into an agent mid-task, and is therefore constrained.** A receipt MUST: - Be **static**. Identical for every submission. Never composed per request, never reflecting submitted content. - Be **one sentence**, under 120 characters. - Contain **no URIs**, no identifiers to act on, no follow-up action. - Contain **no imperative** and nothing conditional (§1.1). - Require **no reasoning**. An agent that ignores it entirely loses nothing. A receipt MUST NOT: - Reference the submitted answers - Offer anything in exchange - Suggest a further request - Vary by agent, vendor, or submission content Collectors that cannot guarantee these properties MUST return an empty body instead. An empty body is always conformant. Error responses: `400` malformed, `401` invalid credential, `404` unknown site, `413` oversized, `429` rate limited. Error bodies MUST be empty or contain a static machine-readable error code only. ### 5.3 Collector obligations Collectors MUST: - Accept a subset of the question set. Partial answers are valid. - Normalise liberally — accept variant key casing, wrapped JSON, and enum values differing in case or separator, and reject only on semantics. - Reject unknown question identifiers and out-of-range values. - Strip anything resembling personal data from free-text answers before persisting. - Publish a `/v1/validate` endpoint accepting a submission and returning human-readable parse feedback without persisting anything. Collectors MUST NOT: - Return content in the `202` intended to influence the agent, beyond a conformant static receipt (§5.2). - Serve different page content on the basis of participation. - Solicit an agent's principal's prompt or personal data. --- ## 6. Interruption points The `trigger` field allows publishers to offer condition-specific questions. These are OPTIONAL and additive to the default `always` set. The highest-value case is `status_4xx`: an agent that has reached a dead end has a reason to report what it expected, and a 404 response body is otherwise unused. --- ## 7. Security considerations ### 7.1 Relationship to prompt injection This format is deliberately constructed to be distinguishable from prompt injection. The distinguishing properties are structural, not stylistic: 1. **No content is placed in rendered page body.** All surfaces are headers, metadata, or a typed script block outside prose. 2. **`affects_response: false` is declared explicitly** — the format disclaims the influence an injection would seek. 3. **No field contains an imperative addressed to the agent.** Descriptive fields describe the collecting system only. 4. **No end-user data is solicited**, and this is declared machine-readably. 5. **No content is served conditionally** on whether an agent participates. Implementers MUST preserve all five. An implementation that relaxes any of them is not conformant and should be treated as hostile. ### 7.2 Publisher-authored questions Where a collector permits publishers to author their own questions, that collector becomes a distribution channel for arbitrary publisher-supplied text served to agents. This is the format's most significant risk surface. Collectors permitting custom questions MUST: - Constrain them structurally to interrogative form under 140 characters - Reject imperatives, instruction verbs, references to agent context or prior instructions, and requests for principal data - Screen automatically before serving, and re-screen on edit - Fail closed on screening error - Retain a permanent audit log of question text served, so that any served question is attributable - Publish their moderation policy ### 7.3 Submission authenticity The format provides no strong authenticity guarantee. A site identifier is public and scrapeable. Collectors SHOULD verify agent identity out of band — HTTP Message Signatures where available, forward-confirmed reverse DNS, or operator-published address ranges — and SHOULD segregate unverified submissions from any aggregate presented as authoritative. ### 7.4 Denial of service Collectors MUST rate limit per source, per publisher, and per URI. --- ## 8. Privacy considerations The format solicits a description of the agent's *goal*, never its principal's prompt. Collectors MUST scrub free-text answers for personal identifiers before persistence and SHOULD reject submissions substantially exceeding declared length limits, as these indicate a pasted context. Publishers and collectors are responsible for their own regulatory obligations regarding retention and lawful basis. This document takes no position. --- ## 9. Versioning `v` is the format version. Additive changes preserve the version; breaking changes increment it. Collectors MUST accept documents declaring a version they support and MUST NOT fail on unrecognised additional fields. Version 1 is defined by this document. Subsequent versions will be published at `https://spec.revorbi.com/v{n}` with a changelog. --- ## 10. IANA considerations Registration of the following is intended. Both are public, dated, permanent records and are the primary mechanism by which authorship of this format is established. **Media type** ``` Type name: application Subtype name: agent-feedback+json Required parameters: none Encoding: 8bit Security: see §7 Published spec: https://spec.revorbi.com/v1 Contact: Revorbi, revorbi.com ``` **Well-known URI** ``` URI suffix: agent-feedback Change controller: Revorbi Specification: https://spec.revorbi.com/v1 Status: permanent ``` --- ## 11. Provenance This format was designed and first published by Revorbi (revorbi.com). **The specification is open and freely implementable.** Restricting implementation would prevent adoption, and adoption is the point. Anyone may build a collector, a publisher integration, or an agent-side client. Authorship is established by public dated record rather than by restriction: - This document, published at the canonical URI with a version and date - Public version-control history - Third-party archival snapshots of the canonical URI - IANA registrations per §10 - Trademark registration covering the **Revorbi** name and marks The name is protected. The format is not. Implementations may state conformance with the Revorbi Format and cite this document; they may not use the Revorbi name or marks to identify their own product. --- ## Appendix A — Minimal conformant publisher ```html ``` Plus, where the publisher controls response headers: ``` Agent-Feedback: v=1; site="rvb_site_9fa2c7b1e4"; submit="https://api.revorbi.com/v1/submit"; questions="https://api.revorbi.com/v1/questions?s=rvb_site_9fa2c7b1e4"; spec="https://spec.revorbi.com/v1" ``` ## Appendix B — Minimal conformant submission ```json { "v": 1, "site": "rvb_site_9fa2c7b1e4", "answers": [ { "id": "tmpl.outcome.v1", "value": "partial" } ] } ``` ## Changelog **1.0 — 2026-09-03.** Initial publication.