Citations v1

URI: https://standards.upperhandai.com/ext/citations/v1
Kind: runtime data Part (card declaration optional)
Media type: application/vnd.upperhand.citations+json
Status: Current
Since: 2026-08-18

Purpose

Every quantitative claim an agent makes must carry an audit trail a human — or another agent — can re-run. Citations travel as typed data Parts alongside the result they support, so workbenches render them beneath the claim, transcripts preserve them, and disputes resolve by re-execution rather than argument.

Runtime Part

Each tool result that states a number is accompanied by a data Part with media type application/vnd.upperhand.citations+json:

{
  "study": "Versant Mega Tracker",
  "period": "W6 (April 2026)",
  "fielded": "2026-04-02/2026-04-19",
  "base": { "name": "Adults 18-74, aware of brand", "n": 4210 },
  "weight": "main_weight",
  "source": {
    "table": "versant_flat",
    "column": "s14r5",
    "function": "extractFunnel"
  },
  "warnings": ["Base under 100 in the 65-74 cell"]
}

Fields

Field	Req.	Meaning
`study`	yes	Dataset name, matching the agent's data-source declaration
`period`	yes	Human-readable snapshot id — wave, date range, or version
`fielded`	no	ISO-8601 date or interval the data was collected
`base`	yes	`{name, n}` — the population the number is computed over, and its unweighted count
`weight`	no	Weight column name, or `"unweighted"`
`source`	yes	`{table, column, function}` — the re-run hook: a named extractor function over a named table/column reproduces the number
`warnings`	no	Array of caveat strings (small bases, coverage gaps)

Agents MAY add domain-specific fields (additionalProperties are allowed); consumers MUST ignore fields they do not recognize.

The source triple is the contract's heart: given access to the agent's documented data layer, function(table, column) re-derives the claim. A citation that cannot be re-run is decoration, not a citation.

Card declaration (optional but recommended)

Agents SHOULD list the media type in defaultOutputModes and MAY declare the extension in capabilities.extensions[] (declarative-only, required: false) so callers know citations are available before the first call.

Consumer requirements

MUST render a result's citation adjacent to the numbers it supports.
MUST preserve citation Parts in stored transcripts.
SHOULD surface warnings with the same prominence as the value.

Conformance requirements

Every invoked skill that returns quantitative JSON also returns a Part of this media type in the same result.
Required fields present; base.n is a positive integer.

The current probe checks presence only and can warn rather than fail; it does not validate this payload or reproduce the result. See probe coverage and acceptance evidence.