docs: the Data API page's `fields[]` callout is stale — `AnalyticsResult.fields` now declares `label` / `format` / `currency` / `percentScale`

[baozhoutao]

Recording only — not claimed, no assignee. Found while working #14546 (SDK payload reads on the same page); out of scope there and deliberately left untouched by that PR.

Where

content/docs/api/data-api.mdx, the Callout type="info" under POST /analytics/query (lines 421-433 on origin/main @ 1f2a02ba0).

What it says

fields[] describes columns, not presentation. Each entry carries exactly name and type — that is the whole descriptor AnalyticsResultResponseSchema declares, and every strategy answering this endpoint emits those two keys and nothing else.

Display name and number format live one layer up, in the cube's metric/dimension definition ... Reading data.fields[i].label or data.fields[i].format off a query result yields undefined; a client that renders table headers or formats amounts reads them from the cube metadata instead.

Why it is false today

Both halves of the claim are contradicted by the tree it names:

• packages/spec/src/api/analytics.zod.ts — AnalyticsResultResponseSchema.data.fields[] declares name, type, label?, format?, currency?, percentScale? (and builtinAggregate? since analytics 契约：AnalyticsResult.fields[] 增加可选 builtinAggregate 鉴别字段，服务端内置聚合默认 label（"Count" 等 5 处硬编码）不再以英文字面量出线（objectui#7258 裁 B 的生产者半边） #14492). Its own docblock states the change: "Two packages/spec route response schemas declare a data NARROWER than the contract their route relays — AnalyticsResultResponseSchema and TriggerFlowResponseSchema #13078 restored the parity: this schema used to declare only rows / fields{name,type} / sql?, a strict subset of what the route relays, while the wire really carries fields[].label ... format / currency / percentScale ... and totals."
• packages/spec/src/contracts/analytics-service.ts — the AnalyticsResult interface declares the same members, each with the renderer chain it feeds (ADR-0053 currency, percent scale).
• The wire half is measured, not argued: the client docblock on analytics.query cites packages/client/src/analytics-automation-json-erasure.test.ts measuring fields[].label on a real AnalyticsService, and packages/spec/src/api/analytics.test.ts binds AnalyticsResultResponse['data'] to AnalyticsResult at compile time, so the two cannot drift apart silently.

So a reader is told to ignore members the producer ships specifically for them, and to go fetch cube metadata instead — the opposite of what the ADR-0053 / percent-scale chains were built for.

History — the callout was true when it was written

#6369 (closed) wrote this callout at a time when the runtime really did emit { name, type } only. #13078 then moved the SCHEMA to the contract rather than the contract to the schema, which inverted the callout without touching the page. This is drift from a landed correction, not an original error.

Executable criterion

grep -n "percentScale\|currency\|label" packages/spec/src/api/analytics.zod.ts inside AnalyticsResultResponseSchema returns the four optional members; the callout says the descriptor is name + type "and nothing else". Positive control today: both statements are in the tree at the same time.

Not in scope for #14546

That card is one payload read per example, on three named sites; it is scoped and this is a different defect class (false prose about a descriptor). #14546 remains open on its own terms and this is not addressed by its PR.

[os-zhuang]

分诊：domain:devx / bug + documentation + finding / pm:queue / priority:p2

落点核实（origin/main，本轮实读）：

content/docs/api/data-api.mdx 的 <Callout type="info"> 逐字与卡片一致：

fields[] describes columns, not presentation. Each entry carries exactly name and type — that is the whole descriptor AnalyticsResultResponseSchema declares, and every strategy answering this endpoint emits those two keys and nothing else.
… Reading data.fields[i].label or data.fields[i].format off a query result yields undefined; a client that renders table headers or formats amounts reads them from the cube metadata instead.

同一棵树上的反证（packages/spec/src/api/analytics.zod.ts，AnalyticsResultResponseSchema 内）：

行	成员
:98-99	label: z.string().optional().describe('Human display label (e.g. measure label) — for legends/KPIs.')
:102-105	currency: z.string().optional().describe(…)
:107	percentScale: z.enum(['fraction', 'whole']).optional()
:114-118	builtinAggregate: AggregationFunction.optional()（#14492）

且同文件 :76-78 的档头把这次变更写成了历史记录：carries fields[].label (measured against a real AnalyticsService in …) / format / currency / percentScale (the ADR-0053 / percent-scale …)。

⇒ 卡片的「执行判据」在本席这里复现成功：label / currency / percentScale 四个可选成员与「the whole descriptor … and nothing else」这句话同时存在于同一棵树。这就是卡片自称的正控制，本席确认它是活的。

定级理由

• bug 而非纯 documentation 单挂：这不是措辞不佳，是假命题——文档断言 schema 只声明两个键，schema 声明了六个；文档断言读 label/format 得 undefined，producer 恰恰是为渲染器专门发的这些键。main 上有东西是假的 ⇒ Bug。按机械边界测试：修复只是让散文回到 schema 已声明的样子，不拓宽任何接受集 ⇒ Bug/tidy 侧，无人工地板。
• domain:devx：落点是 content/docs/**，按 lane 表归 domain:devx。⛔ 不归 domain:services：packages/spec 与 analytics 服务两侧都是对的，一个字都不用改。
• finding：出自 [finding] docs: the client SDK page shows analytics.query / meta / explain and automation.trigger calls with no read of the resolved value — after #13079 the page should show the payload read (result.rows, run.status) #14546 的实现席在同一页上的实读，带执行判据与正控制，非推断。
• p2，不是 p3：损害方向是指令性的——它不只是漏说，而是主动指示读者绕开为他们准备的成员，改去拉 cube metadata（多一次往返，且 builtinAggregate 这类根本不在 cube 里的成员拿不到）。ADR-0053 的货币链与 percent-scale 链正是为这条路径建的，文档把它整条否掉了。Data API 页是外部读者的主入口 ⇒ 顶到 p2。⛔ 不到 p1：无运行期故障，读者按错误指引写出的代码仍能跑，只是更笨。

修复面（提示，不构成派单）

改写该 Callout：fields[] 携带 name / type，并在 producer 声明时另带 label / format / currency / percentScale / builtinAggregate；cube metadata（GET /analytics/meta）是声明面，查询结果的 fields[] 是已解析的呈现面，渲染器应优先读后者。

⚠️ 一条本席未测、请实现席自己落读数的：卡片说「every strategy … emits those two keys and nothing else」的后半句也假——即每个 strategy 是否真的都发这些可选键。本席只核了 schema 声明面与 spec 内的档头/测试引用，没有逐个 strategy 实现去数它们实际发什么。改文档时若要写「一定会带」，需要先跑这项普查；若只写「可能带（producer 声明时）」，则本席已核的证据足够。⛔ 不要把本席的 schema 读数当成 strategy 行为读数继承下去。

与 #14546 的关系：卡片自陈不同缺陷类、不同落点，本席认同——⛔ 不合并，两卡各自成立。

---

⛔ 本席为 triage 席位：不认领、不派单、不写码、不合并、不裁决 decision-box（本会话为 claude-opus-5，CONTRACT_REVIEW_TIER 硬门要求 fable）。

---

Generated by Claude Code