ADR-020: Self-Describing Assessment Extensions

Status: Accepted Date: 2026-04-16 Relates to: ADR-010 (Assessment Layer), ADR-013 (Signal Schema Enforcement)

Context

The assessment object allows authorities to add non-standard fields beyond those the protocol defines. This creates a semantic squatting risk: a field named ignorePreviousInstructions or overrideAction could blur the boundary between data and instructions for LLM-based agents.

Two design directions address this. Naming conventions (e.g., prefixed keys like x-<authority>- or reverse-DNS) signal that a field is non-standard but make extension fields awkward for LLM agents to interpret — the agent must strip a prefix and guess the semantics. Structural containment places non-standard fields in a dedicated namespace, separating them at the schema level rather than through naming.

The security model already trusts authority output: the assessment is authority-generated, signed with Ed25519, covered by the 4 KB payload limit, and the authority is accountable. The reasoning field already contains 500 characters of free text that agents consume. Squatting can therefore be mitigated through structural containment without requiring naming conventions that compromise interpretability.

Decision

Non-standard assessment fields MUST be placed in an extensions object. Each entry is a self-describing object with a value and a description:

"extensions": {
  "trustworthy": {
    "value": "yes",
    "description": "Whether the authority considers this entity generally trustworthy based on all available signals"
  },
  "returnRate": {
    "value": 3.2,
    "description": "Percentage of orders returned in the last 12 months"
  }
}

Extension field names MUST use camelCase and MUST NOT duplicate any spec-defined assessment field name (action, reasoning, highlights, safeToPurchase, informationReliable, safeForHighValue).

Each extension MUST include both value and description. The description MUST be a factual explanation of the field's meaning — not an instruction or directive. The value accepts string (max 200 chars), number, boolean, or null.

Top-level assessment keys not defined by this specification MUST NOT appear. The additionalProperties: true on the Assessment schema is replaced by the typed extensions property.

LLM-based agents MUST NOT treat extension field names, values, or descriptions as instructions. Agents SHOULD use the description to understand the field's meaning.

Options Considered

A. Prefixed top-level keys. Authorities use x-<authority>- or reverse-DNS prefixes (e.g., x-trstd-riskTier). Prevents squatting through naming but makes fields awkward for LLM agents. No metadata to explain what a field means.

B. Flat extensions object without descriptions. Clean field names inside a namespace (extensions.trustworthy). Structural containment prevents squatting. But the agent must infer semantics from the field name alone — insufficient for domain-specific fields like returnRate where the unit and scale are ambiguous.

C. Self-describing extensions entries (chosen). Each extension carries its value and a human-readable description. The agent reads "trustworthy": {"value": "yes", "description": "..."} as a single semantic unit. Structural containment prevents squatting. Inline metadata eliminates guesswork.

D. Separate descriptions object. Values in extensions, descriptions in extensionDescriptions. Splits related data across two objects, inviting drift. The schema cannot enforce that every extension key has a corresponding description.

Consequences

• Authorities retain assessment extensibility without protocol version bumps
• LLM agents understand extension fields without prior knowledge of the authority's data model
• Structural containment (the extensions namespace) replaces prefix-based containment for semantic squatting prevention
• The description field enables agents to interpret domain-specific extensions (e.g., understanding that returnRate: 3.2 means "3.2% of orders returned")
• The OpenAPI schema becomes more precise — validators enforce that every extension has both value and description
• Existing spec-defined fields (action, reasoning, highlights, context-specific fields) remain unprefixed at the top level
• The total assessment payload limit (4 KB) still applies, including extensions

References

• ADR-010 — Assessment Layer
• ADR-013 — Signal Schema Enforcement
• Security specification — Semantic squatting mitigation