Skip to content

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

New issue
New issue
Closed
#16234
Closed
docs: the Data API page's fields[] callout is stale — AnalyticsResult.fields now declares label / format / currency / percentScale#16141
#16234
Labels
bugSomething isn't workingdocumentationImprovements or additions to documentationdomain:devxDomain lane — seat card indexed by label:pm:seatfindingRecorded observation — held, not dispatchable until the findings triage round grades itpriority:p2Medium: important, M3

Description

@baozhoutao
baozhoutao
opened on Sep 6, 2026

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:

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.

Activity

  1. os-zhuang
    added
    bugSomething isn't working
    documentationImprovements or additions to documentation
    priority:p2Medium: important, M3
    pm:queueReady for the PM dispatch loop
    domain:devxDomain lane — seat card indexed by label:pm:seat
    findingRecorded observation — held, not dispatchable until the findings triage round grades it
    on Sep 6, 2026

  2. os-zhuang commented on Sep 6, 2026

    @os-zhuang
    os-zhuang
    on Sep 6, 2026 – with Claude
    Contributor

    分诊：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

  3. claude
    assigned
    baozhoutao
    on Sep 6, 2026
  4. claude
    added
    pm:dispatchedDispatched to a dev agent by /pm-dispatch
    and removed
    pm:queueReady for the PM dispatch loop
    on Sep 6, 2026

  5. claude commented on Sep 6, 2026

    @claude
    claudeBot
    on Sep 6, 2026 – with Claude
    Contributor

    Claim: PM loop round 1 — FAMILY member, folded into chain head #15982
    Session: session_01Vbw3RPgdtqesx4azk9SbW8
    Branch: claude/issue-15982-published-prose-vs-schema (shared with #15982; this card's edit is its own commit and its own Fixes #16141 line in the one PR)
    Worktree: objectstack-issue-15982
    Domain: domain:devx
    File surface: content/docs/api/data-api.mdx — the fields[] callout under POST /analytics/query (:421-433 on origin/main)
    Container & model: M, mode:subagent, model: opus
    Clause-②: no
    Serial constraints cleared: see the chain-head claim on #15982 (06:1xZ) — fold gates ①–⑤ answered there; no open PR touches this file.

    Generated by Claude Code

  6. claude commented on Sep 6, 2026

    @claude
    claudeBot
    on Sep 6, 2026 – with Claude
    Contributor

    Fixed in draft PR #16234 (branch claude/issue-15982-published-prose-vs-schema), as the second commit of the two-card family headed by #15982. The full os-dev-report for this run is posted on #15982.

    The callout now states the conditional form the schema supports — fields[] carries name / type and, when the producer declares them, label / format / currency / percentScale / builtinAggregate — and both false sentences are gone. No strategy census was run, so nothing claims every strategy always emits these keys, per triage.

    Generated by Claude Code

  7. claude commented on Sep 6, 2026

    @claude
    claudeBot
    on Sep 6, 2026 – with Claude
    Contributor

    ACCEPT (family member) — delivered on PR #16234 with chain head #15982; full review there (PM seat domain:devx @ objectstack, 07:1xZ). The fields[] callout under POST /analytics/query now states the six members AnalyticsResultResponseSchema declares in the conditional form triage required, names cube metadata as the declaration surface, and records (re-verified at analytics.zod.ts:155-174, #6442) that format is not reachable through GET /analytics/meta. Own commit, own Fixes #16141 line. pm:dispatched is stripped in the landing stroke.

    Generated by Claude Code

  8. baozhoutao
    closed this as completedin #16234on Sep 6, 2026
  9. claude
    unassigned
    baozhoutao
    on Sep 6, 2026
  10. claude
    removed
    pm:dispatchedDispatched to a dev agent by /pm-dispatch
    on Sep 6, 2026

  11. claude commented on Sep 6, 2026

    @claude
    claudeBot
    on Sep 6, 2026 – with Claude
    Contributor

    LANDED — PR #16234 MERGED via the merge queue as 0e16fc454 at 2026-09-06T07:55:04Z (added_to_merge_queue 07:20:42Z → merged + removed_from_merge_queue at the same second = a landing). PM seat domain:devx @ objectstack, session session_01Vbw3RPgdtqesx4azk9SbW8, 2026-09-06T07:58Z.

    Content probe on re-fetched origin/main @ 0e16fc454 via git show: the new callout lead (is the resolved presentation surface) = 1 and the format projection fact (with \format` dropped) = 1 — in place in content/docs/api/data-api.mdx; **negative controls**: and nothing else= 0,yields `undefined`= 0 (both absent); firing controlAnalyticsResultResponseSchema` = 1; nonsense 0.

    Same stroke: pm:dispatched stripped and the assignee cleared (GitHub closes the card through Fixes and leaves labels — #16005). Ownership labels stay.

    Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingdocumentationImprovements or additions to documentationdomain:devxDomain lane — seat card indexed by label:pm:seatfindingRecorded observation — held, not dispatchable until the findings triage round grades itpriority:p2Medium: important, M3

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions