revorbi ·
canonical URI https://spec.revorbi.com/v1 ·
source
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.
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.
These are normative. An implementation violating any of them is not conformant.
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
<link> 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:
Plain HTTP, open schema, no dependency on any AI provider's conventions.
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.
The format must not solicit an agent's principal's prompt, personal information, or identifying details. Questions concern page content only.
No enforcement mechanism. No penalty for non-participation. No differential content served on the basis of whether an agent responded.
Key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119.
A publisher SHOULD expose all surfaces below. No single surface reaches every agent.
Agent-Feedback: v=1;
site="<site-identifier>";
submit="<absolute-uri>";
questions="<absolute-uri>";
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.
/.well-known/agent-feedback — media type application/agent-feedback+json.
{
"v": 1,
"site": "<site-identifier>",
"submit": "<absolute-uri>",
"questions": "<absolute-uri>",
"spec": "https://spec.revorbi.com/v1",
"optional": true,
"affects_response": false,
"recipient": "site_owner",
"collects_user_data": false,
"note": "<descriptive text, see §1.1>"
}
<link rel="agent-feedback" href="<absolute-uri>">
<meta name="agent-feedback" content="<site-identifier>">
The minimum viable surface. Present where a publisher cannot emit headers.
Requires the agent to parse <head>.
Agent-Feedback: <absolute-uri>
Non-standard but zero-cost, and some agents fetch robots.txt as a matter of
course.
Publishers SHOULD carry the question document inside an existing
application/ld+json block as an additionalProperty:
{
"@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.
Publishers SHOULD inline the question document so that participation requires no discovery fetch:
<script type="application/agent-feedback+json">
{ …question document… }
</script>
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.
Retrieved from the questions URI, or inlined per §3.6.
{
"v": 1,
"site": "<site-identifier>",
"submit": "<absolute-uri>",
"spec": "https://spec.revorbi.com/v1",
"set_id": "<opaque>",
"set_version": 7,
"cache_ttl": 3600,
"optional": true,
"affects_response": false,
"recipient": "site_owner",
"collects_user_data": false,
"note": "<descriptive text>",
"questions": [
{
"id": "<stable identifier>",
"q": "<question text>",
"type": "enum",
"opts": ["found", "partial", "none", "ambiguous"],
"required": false
},
{
"id": "<stable identifier>",
"q": "<question text>",
"type": "text",
"max": 300,
"required": false
}
],
"example": { "answers": [ … ] }
}
id values MUST be stable. Changing a question's meaning requires a new id.ETag and honour If-None-Match.example — agents reproduce examples more reliably
than they follow schemas.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. |
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."
POST to the submit URI. Content-Type: application/json.
{
"v": 1,
"site": "<site-identifier>",
"set_id": "<opaque>",
"set_version": 7,
"trigger": "always",
"agent": {
"vendor": "<self-declared>",
"model": "<self-declared>",
"purpose": "answer_question"
},
"answers": [
{ "id": "<stable identifier>", "value": "partial" },
{ "id": "<stable identifier>", "text": "…" }
]
}
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.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.
{ "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:
A receipt MUST NOT:
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.
Collectors MUST:
/v1/validate endpoint accepting a submission and returning
human-readable parse feedback without persisting anything.Collectors MUST NOT:
202 intended to influence the agent, beyond a
conformant static receipt (§5.2).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.
This format is deliberately constructed to be distinguishable from prompt injection. The distinguishing properties are structural, not stylistic:
affects_response: false is declared explicitly — the format disclaims
the influence an injection would seek.Implementers MUST preserve all five. An implementation that relaxes any of them is not conformant and should be treated as hostile.
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:
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.
Collectors MUST rate limit per source, per publisher, and per URI.
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.
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.
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
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:
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.
<meta name="agent-feedback" content="rvb_site_9fa2c7b1e4">
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"
{
"v": 1,
"site": "rvb_site_9fa2c7b1e4",
"answers": [
{ "id": "tmpl.outcome.v1", "value": "partial" }
]
}
1.0 — 2026-09-03. Initial publication.