ADR-004: Response Format and Trust Scoring

Status: Accepted Date: 2026-03-20

Context

The /v1/entities/{entityId}/trust-signals endpoint returns trust signals (ADR-002, ADR-003). The protocol must decide how to express trust levels. Should it return raw facts, a composite score, or something in between?

This decision affects how agents consume the data and whether the protocol embeds an opinion about trustworthiness.

Decision

Return signals with verification metadata. Each signal carries its type and the date the authority last verified it. The protocol does not compute or return a composite trust score.

Signal Metadata Fields

Every signal includes these metadata fields alongside its type-specific data:

Field	Type	Description
type	string	Signal type from the taxonomy (ADR-003)
verifiedAt	RFC 3339 datetime (UTC)	When this signal was last verified
data	object	Type-specific signal data

The envelope is intentionally minimal. Fields like source (which authority produced the signal) and confidence (verification rigor) were considered but deferred — in a single-authority model they add no information. They can be added if the ecosystem grows to support federated signals from multiple authorities (see roadmap).

Response Envelope

The full response wraps signals with entity-level metadata:

{
  "meta": {
    "responseId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "entityId": "d6f2fdf4-f829-4ce6-a1cc-e2bd957709db",
    "status": "verified",
    "url": "https://www.example.org/de/products/123",
    "context": "purchase",
    "timestamp": "2026-03-23T14:30:00Z",
    "expires": "2026-03-24T14:30:00Z"
  },
  "signals": [ ... ],
  "kid": "authority-key-1",
  "signature": "pV2qFz8kRn0LhVbUqSSR3IyzQlDu5XbE0MwvMXfBjlNRqIjmGT6c2Eq..."
}

• meta.responseId — UUID (v4) uniquely identifying this response. Reserved for future use by transparency mechanisms tracked on the roadmap.
• meta.entityId — The queried entity identifier
• meta.status — Entity verification status: verified, lapsed, revoked, or pending
• meta.url — The canonical form of the URL the authority validated against entity scope. Binds the signed response to the specific page the agent asked about. See ADR-007 — Binding the Signed Response to the Request.
• meta.context — The context value the authority used. Echoes the context query parameter; omitted when the agent sent no context. See ADR-007 — Binding the Signed Response to the Request.
• meta.timestamp — When this response was generated
• meta.expires — After this time, agents MUST re-query rather than use cached data
• signature — Cryptographic signature over the response (see ADR-007)

Options Considered

A. Raw signals only. Return factual data without metadata. Protocol stays neutral. Every agent reimplements provenance assessment. Agents cannot distinguish between a signal verified yesterday and one verified two years ago.

B. Composite trust score. Return a single 0–100 score alongside signals. Easy for agents to consume. Opaque — scoring methodology becomes political. Creates a gaming incentive (optimize for the score, not actual trustworthiness).

C. Signals with verification metadata (chosen). Return facts with context: what type of signal and when it was last verified. Agents make informed decisions. The protocol provides evidence, not judgement. The envelope stays minimal for v1 and can grow as the ecosystem matures.

Consequences

• The protocol remains neutral — it does not define "trustworthy"
• Agents (or their platforms) implement their own trust policies using signal data and verification dates
• Different agents can reach different conclusions from the same data, which is correct — a personal shopping agent and an enterprise procurement agent have different risk tolerances
• The minimal envelope (type, verifiedAt, data) keeps signals lightweight; additional metadata fields can be added in future versions without breaking existing consumers

References

• ADR-002 — Verification Endpoint Schema (response structure)
• ADR-003 — Trust Signal Taxonomy (what signals exist)