Skip to main content

ADR-014: Replace verified Boolean with status Enum

Status: Accepted Date: 2026-03-25 Relates to: ADR-004 (Response Format)

Context​

The verify response meta object uses a verified boolean to express the entity's trust state. Combined with a 404 for unknown entities, the protocol has three effective states: actively verified (true), lapsed (false), and unknown (404).

A boolean hides distinctions that agents need. An entity with verified: false could mean expired compliance (benign), active revocation for fraud (severe), or a pending application (neutral). Agents cannot differentiate these cases without out-of-band information. The problem grows as the protocol matures — new trust states will emerge, and a boolean cannot accommodate them.

Decision​

Replace verified: boolean with status: string using a closed enum:

ValueMeaning
verifiedActively verified by the authority
lapsedVerification expired (e.g., expired compliance, missed renewal)
revokedVerification withdrawn by the authority (e.g., fraud, policy violation)
pendingApplication received, not yet confirmed

A 404 (entityNotFound) continues to mean the entity is unknown to the authority.

The enum is intentionally small. Each value represents a distinct risk profile that agents handle differently:

  • verified — proceed normally
  • lapsed — treat with caution; the provider was previously verified
  • revoked — treat as a negative signal; the authority actively removed trust
  • pending — no trust signals yet; the provider is in the verification pipeline

Options Considered​

A. Keep verified boolean and document the state model. No schema change. Agents still cannot distinguish revoked from lapsed. The documentation improves understanding but not interoperability.

B. Replace verified: boolean with a status enum (chosen). Four values cover the states agents encounter. The enum is extensible. Agents can switch on the value rather than interpreting a boolean plus error codes.

C. Keep verified and add a statusReason field. Backward-compatible but awkward — verified: false with statusReason: "revoked" duplicates semantics across two fields. Agents must check both.

Consequences​

  • The meta.status field replaces meta.verified in the response schema, OpenAPI spec, and all normative documentation
  • Agents switch on a string enum instead of a boolean — more explicit branching logic
  • The enum is extensible; new values can be added in a future revision without breaking the field type
  • Existing agents that checked verified: true must update to check status === "verified"
  • The 404 semantics for unknown entities remain unchanged