Skip to content

fix: document raw JSON as objects and byte fields as base64 strings - #30123

Merged
nickvigilante merged 4 commits into
mainfrom
fix-swagger-json-types
Nov 5, 2026
Merged

nickvigilante merged 4 commits into
mainfrom
fix-swagger-json-types

Conversation

@nickvigilante

@nickvigilante nickvigilante commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Swagger renders json.RawMessage and []byte fields as integer arrays, so the API reference showed chat tool calls as "args": [0] even though tool arguments and results are JSON values.

Render every json.RawMessage as an object with one .swaggo replace rule, and tag []byte fields, which JSON-encode as base64, swaggertype:"string" format:"byte". This covers ChatMessagePart.args, .result, .data, ToolResult.output, DynamicTool.input_schema, both workspace build state fields, TemplateBuilderModuleVariable.default, and CreateTestAuditLogRequest.additional_fields.

ChatMessagePart.provider_metadata is internal only, so it is hidden with swaggerignore:"true" like its siblings. ChatMessagePart.result and ToolResult.output can hold any JSON value, and TemplateBuilderModuleVariable.default holds a string, number, or boolean, so object is an approximation for all three and the field comments say so. swag rejects an untyped .swaggo override for json.RawMessage.

Part of DOCS-1122, split from #30121.


🤖 Built with AI assistance.

@linear-code

linear-code Bot commented Sep 29, 2026

Copy link
Copy Markdown

DOCS-1122

@nickvigilante
nickvigilante marked this pull request as ready for review September 29, 2026 20:05
@matifali
matifali removed their request for review October 1, 2026 05:23
@nickvigilante
nickvigilante requested a review from matifali October 1, 2026 21:00
@matifali
matifali removed their request for review October 2, 2026 12:48
@nickvigilante nickvigilante added the api Area: HTTP API label Oct 5, 2026
@matifali
matifali removed their request for review October 14, 2026 18:35
@nickvigilante
nickvigilante force-pushed the fix-swagger-json-types branch from 72d7095 to 0283447 Compare October 29, 2026 02:08
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review

coder-agents-review Bot commented Oct 29, 2026 •

Copy link
Copy Markdown
Contributor

Chat: Review posted | View chat
Requested: 2026-10-29 03:18 UTC by @nickvigilante

Review history
  • R1 (2026-10-29): 9 reviewers, 6 P3, 3 P4, COMMENT. Review
  • R2 (2026-10-29): 8 reviewers, 6 P3, 3 P4, COMMENT. Review
  • R3 (2026-10-29): 9 reviewers, 7 P3, 6 P4, COMMENT. Review
  • R4 (2026-10-29): 5 reviewers, 7 P3, 7 P4, COMMENT. Review
  • R5 (2026-10-29): 4 reviewers, 7 P3, 7 P4, APPROVE. Review

deep-review v0.13.0 | Round 5 | 2255794..8677a48

Last posted: Round 5, 14 findings (7 P3, 7 P4), APPROVE. Review

Finding inventory

Finding inventory: PR #30123

Findings

# Sev Status Location Summary Round Reviewer Posted
CRF-1 P3 Author fixed (1e125cd) codersdk/chats.go:586 ProviderMetadata documented as object but always stripped; siblings use swaggerignore R1 Netero Yes
CRF-2 P3 Author fixed (1e125cd) codersdk/chats.go:874 ToolResult.output documented as object but endpoint accepts any JSON value R1 Netero Yes
CRF-3 P3 Author fixed (1e125cd) codersdk/chats.go:565 ChatMessagePart.result documented as object but holds strings, numbers, arrays R1 Netero, Melody Yes
CRF-4 P4 Author fixed (1e125cd) codersdk/templatebuilder.go:27 TemplateBuilderModuleVariable.default documented as object but catalog defaults are scalars R1 Netero Yes
CRF-5 P3 Author fixed (fcebe8e) codersdk/chats.go:556 Per-field object tags; one .swaggo replace line covers all current and future json.RawMessage fields R1 Meruem, Pariston, Ryosuke Yes
CRF-6 P4 Author fixed (PR description edit) codersdk/templatebuilder.go:27 PR description proposes an untyped .swaggo override that swag rejects R1 Razor, Pariston, Ryosuke Yes
CRF-7 P3 Author fixed (1e125cd) codersdk/workspacebuilds.go:218 UpdateWorkspaceBuildStateRequest.state rendered as plain string; docs never say base64 R1 Leorio Yes
CRF-8 P3 Author fixed (1e125cd) codersdk/workspaces.go:125 CreateWorkspaceBuildRequest.state rendered as plain string; docs never say base64 R1 Leorio Yes
CRF-9 P4 Author fixed (1e125cd) codersdk/chats.go:576 ChatMessagePart.data has empty Description; sibling ChatAttachmentFile.data says base64 R1 Leorio Yes
CRF-10 Note Dropped by orchestrator (affirmation of PR description, no information for author) PR description Description precedent claims verified R1 Leorio No
CRF-11 Note Dropped by orchestrator (verification with no defect, already covered by Netero checks) codersdk/chats.go:556 Generated swagger.json matches generator; coverage claim holds R1 Razor No
CRF-12 OOS Out of scope (body) scripts/apitypings/main.go:138 json.RawMessage maps to Record<string, string> in TypeScript R1 Melody No
CRF-13 OOS Out of scope (body) coderd/workspacebuilds.go:1059 GET state annotated as WorkspaceBuild but returns raw state bytes R1 Leorio No
CRF-14 OOS Out of scope (body) codersdk/chats.go:583 ProviderMetadata comment repeats "raw JSON" from the type R1 Gon No
CRF-15 OOS Out of scope (body) codersdk/chats.go:2222 InputSchema comment repeats the JSON key from the tag R1 Gon No
CRF-16 Note Note (body) site/src/api/typesGenerated.ts:10775 New "any JSON value" comments sit above Record<string, string> types (CRF-12 now visible) R2 Netero No
CRF-17 OOS Out of scope (body) codersdk/chats.go:639 StripInternal clears context_file_* and skill_dir fields that still appear in swagger docs R2 Razor No
CRF-18 OOS Out of scope (body) coderd/templatebuilder/catalog.go:130 Catalog loader never checks Default against Type, which the new comment states R2 Mafuuu No
CRF-19 P3 Author fixed (PR body restored) PR description PR body describes a different change (idpsync params, x-example, TestEndpointsDocumented), not this diff R3 Netero Yes
CRF-20 OOS Out of scope (body) codersdk/audit.go:261 Older swaggertype:"object" tags on AuditLog.AdditionalFields and oauth2 JWKS are now redundant with the .swaggo rule R3 Netero No
CRF-21 P4 Author fixed (8677a48) .swaggo:11 New .swaggo comment restates the rule and omits that object is an approximation chosen because swag rejects untyped R3 Gon P2, Leorio P4 Yes
CRF-22 P4 Author fixed (8677a48) codersdk/templatebuilder.go:27 Default comment names Go field "Type" and does not say the value is a string, number, or boolean R3 Leorio Yes
CRF-23 P4 Author fixed (PR title edit) PR title Title says "real Swagger types", but object is not the real type of result, output, default R3 Leorio Yes
CRF-24 OOS Out of scope (body) coderd/coderdtest/swagger_test.go:59 No guard for untagged []byte fields; TestSDKFieldsFormatted could assert swaggertype string/format byte R3 Pariston No
CRF-25 OOS Out of scope (body) .swaggo:9 Existing NullUUID and NullTime comments restate their replace lines R3 Gon No
CRF-26 P4 Author fixed (PR description edit) PR description Description says TemplateBuilderModuleVariable.default can hold any JSON value; new field comment says string, number, or boolean R4 Leorio Yes
CRF-27 Note Dropped by orchestrator (fix verification, no information for author) .swaggo:11 CRF-21 and CRF-22 fixes verified R4 Leorio No
CRF-28 Note Dropped by orchestrator (praise, no information for author) .swaggo:14 PR is one logical change; generated output matches R4 Kite No

Contested and acknowledged

CRF-5 (P3, codersdk/chats.go:556) - Per-field object tags vs one .swaggo replace line

  • Finding: Reviewers proposed replacing the seven per-field swaggertype:"object" tags with one replace encoding/json.RawMessage object line in .swaggo, verified to produce identical swagger.json output, so future json.RawMessage fields do not regress to integer arrays.
  • Author defense (R2, PRRC_kwDOGkVX1s8AAAABBr7C7A): Per-field tags are the existing pattern in codersdk/audit.go and codersdk/oauth2.go; a .swaggo replace is a repo-wide rule change affecting every json.RawMessage the generator reaches, so it is out of scope for this PR. Called it "a reasonable follow-up" with no ticket. Author resolved the thread.
  • Panel re-raise (R2, 0/3 accept): Meruem, Pariston, and Ryosuke, each the same agent that raised the finding in R1, re-raised it. Meruem and Ryosuke independently re-ran at 1e125cd: removing every swaggertype:"object" tag on json.RawMessage fields (the PR's plus the older audit.go and oauth2.go tags) and adding replace encoding/json.RawMessage object to .swaggo yields a swagger.json identical to the committed one, so the "repo-wide rule change" alters no current schema and only affects fields added later, the case the finding covers. The cited precedent is the same per-field tag that was missing on 7 of 11 fields before the PR. No ticket linked. Needs a fix, a ticket, or human acceptance.

Round log

Round 1

Netero first pass: 3 P3, 1 P4, no P0, panel proceeded. Full panel (round 1): Ging-Go, Ryosuke, Melody, Pariston, Mafuuu, Gon, Leorio, Razor, wildcard Meruem (random draw). Focused size target 6-8 plus wildcard. Ging-Go and Mafuuu: no findings. Convergence: Meruem, Pariston, Ryosuke independently verified a .swaggo replace encoding/json.RawMessage object line reproduces the PR output for all seven json.RawMessage fields (CRF-5). Razor, Pariston, Ryosuke verified swag rejects interface{}/any replacements (CRF-6), so CRF-2/3/4 fix is a field doc comment, not an untyped schema. Gon's two P2 comment findings target unchanged comment lines; moved to out of scope. Orchestrator verified CRF-13 and CRF-7 evidence (coderd/workspacebuilds.go:1059,1081, docs/reference/api/builds.md:1402,2009). Totals: 6 P3, 3 P4, 2 dropped Notes, 4 out of scope. Reviewed against 2255794..0283447.

Round 2

Fix round (no files added or renamed, no exported signature changes, same goal, effective additions +16). Churn guard PROCEED: CRF-1..4, CRF-6..9 addressed; CRF-5 contested. Netero: no findings, one Note (CRF-16). Panel: Meruem, Pariston, Ryosuke (contested; reused R1 agents via message_agent), Leorio and Gon (doc comments touched), Razor (PR description changed), Ging-Go (.go changed), wildcard Mafuuu (random draw). Ging-TS not spawned: the only .ts change is generated site/src/api/typesGenerated.ts (comment propagation from the Go fields). Fixes verified by Netero, Pariston, Ryosuke, Razor (regenerated swagger.json matches committed). CRF-5 re-raised 0/3 accept. New: 1 Note (body), 2 out of scope. Reviewed against 2255794..1e125cd.

Round 3

Restructure round: the PR body was replaced with text describing a different change (idpsync params, x-example, TestEndpointsDocumented), which states a different goal. Code change since R2 (fcebe8e) only adds the .swaggo rule and drops the PR's per-field json.RawMessage tags. Churn guard PROCEED: CRF-5 addressed (verified by Ryosuke, Melody, Pariston, Netero regen). Netero: CRF-19 (P3, PR body), CRF-20 (OOS). Full panel: Ging-Go, Ryosuke, Melody, Pariston, Mafuuu, Gon, Leorio, Mafu-san (agent-authored PR text), wildcard Razor (random draw). Size 8 plus wildcard. Ging-Go, Ryosuke, Melody, Mafuuu, Mafu-san, Razor: no findings.
Cross-check: CRF-21 convergent (Gon P2, Leorio P4). Keep-argument for P2: the comment is the only place a future editor learns object is an approximation, so a later scalar json.RawMessage field silently gets a wrong schema. Settled P4: the consequence it guards against is a conditional future doc inaccuracy of the class rated P3/P4 in R1, and an attempt to switch to any fails make gen loudly. Gon re-raised CRF-14 and CRF-15 as P2; kept out of scope because git diff 2255794d65..HEAD shows the InputSchema declaration and both comment blocks unchanged vs base (Gon's "modified declaration" evidence compared against R2, not base); ProviderMetadata's tag changed but its comment's accuracy does not depend on the tag. Pariston's P4 []byte guard moved to out of scope (CRF-24): the fix is a new assertion in an unchanged test file, the PR's per-field []byte tags are the only mechanism swag offers, and nothing in this PR goes wrong without it. Totals new: 1 P3, 3 P4, 3 OOS. Reviewed against 2255794..fcebe8e.

Round 4

Fix round (commit 8677a48 changes only the .swaggo comment and the Default comment plus generated copies; title refined to the same goal). Churn guard PROCEED: CRF-19, CRF-21, CRF-22, CRF-23 addressed. Netero: no findings. Panel: Gon, Leorio (their findings' comments changed), Ging-Go, Ryosuke (.go and .swaggo changed), wildcard Kite (random draw). Gon, Ging-Go, Ryosuke: no findings. Fixes verified by Netero, Ryosuke, Leorio (regen matches committed output; TestEndpointsDocumented|TestSDKFieldsFormatted pass per Netero). New: CRF-26 (P4, Leorio); two Notes dropped. Reviewed against 2255794..8677a48.

Round 5

Fix round: head unchanged at 8677a48; only the PR description changed. Churn guard PROCEED: CRF-26 addressed. Netero: no findings (unchanged-diff skip not applied because round 4 was a panel round). Panel: Leorio (raised CRF-26), Pariston and Mafu-san (to reach the 3-reviewer minimum; PR text), wildcard Knov (random draw). No domain specialists: no files changed since round 4. All reviewers: no findings. All in-scope findings closed. Out-of-scope items CRF-12, 13, 14, 15, 17, 18, 20, 24, 25 remain for a human decision. Reviewed against 2255794..8677a48.

About deep-review

CRF = Coder Review Finding (P0-P4, Nit, Note)

Reviewer Focus
Bisky tests
Chopper ops/errors
Churn-guard change verification
Ging language modernization
Gon naming
Hisoka edge cases
Killua perf
Kite change integrity
Knov contracts
Knuckle SQL
Komugi flake/determinism
Kurapika security
Law decomposition
Leorio docs
Luffy product
Mafu-san process
Mafuuu contracts
Melody dispatch/pairing
Meruem structural
Nami frontend
Netero mechanical checks
Pariston premise testing
Pen-botter product gaps
Razor verification
Robin duplication
Ryosuke Go arch
Takumi concurrency
Zoro shape

🤖 Managed by Coder Agents.

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This PR adds swaggertype tags to seven json.RawMessage fields and three []byte fields so the API reference stops rendering them as integer arrays. Regenerating the docs at head reproduces the committed output. Findings: 6 P3, 3 P4.

Out of scope (needs a ticket or explicit acceptance by a human):

  • scripts/apitypings/main.go:138: json.RawMessage maps to map[string]string, so ChatToolCallPart.args, DynamicTool.input_schema, and AuditLog.additional_fields are typed Record<string, string> in typesGenerated.ts. TypeScript code that trusts the type treats nested objects, numbers, and booleans as strings.
  • coderd/workspacebuilds.go:1059: GET /workspacebuilds/{workspacebuild}/state is annotated @Success 200 {object} codersdk.WorkspaceBuild, but the handler writes the raw provisioner state bytes, so the reference documents a response body the endpoint never returns.
  • codersdk/chats.go:583: the ProviderMetadata comment says "as raw JSON", which the json.RawMessage type already states.
  • codersdk/chats.go:2222: the InputSchema comment repeats the input_schema key that the struct tag already shows.

🤖 This review was automatically generated with Coder Agents.

Comment thread codersdk/chats.go Resolved
Comment thread codersdk/chats.go Resolved
Comment thread codersdk/chats.go Resolved
Comment thread codersdk/chats.go Resolved
Comment thread codersdk/templatebuilder.go Resolved
Comment thread codersdk/templatebuilder.go Resolved
Comment thread codersdk/workspacebuilds.go Resolved
Comment thread codersdk/workspaces.go Resolved
Comment thread codersdk/chats.go Resolved
Hide ProviderMetadata from the API reference like its internal-only
siblings, and describe the any-JSON and base64 fields in their doc
comments so the reference tells clients what to send.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The new commit addresses 8 of the 9 round 1 findings: provider_metadata is hidden with swaggerignore, the any-JSON fields and the three base64 fields have field comments that reach the schema, and the PR description no longer proposes the untyped override. Regenerating the docs at 1e125cd reproduces the committed output. One P3 remains open: the .swaggo thread is reopened below. If it is not fixed in this PR and no ticket is linked, a human needs to accept the gap.

Out of scope (needs a ticket or explicit acceptance by a human):

  • codersdk/chats.go:639: StripInternal clears context_file_content, context_file_os, context_file_directory, skill_dir, and context_file_skill_meta_file, but those fields have no swaggerignore:"true", so the API reference lists response fields that clients never receive.
  • coderd/templatebuilder/catalog.go:130: the catalog loader never checks a module variable's default against its type, so a future manifest that breaks the new "Default is a JSON value that matches Type" comment loads without error. All 110 shipped defaults match today.

Notes:

  • site/src/api/typesGenerated.ts:10775: the new "can be any JSON value" comments now sit directly above Record<string, string> types for ToolResult.output and TemplateBuilderModuleVariable.default, which makes the round 1 out-of-scope apitypings mapping visible on adjacent lines.

🤖 This review was automatically generated with Coder Agents.

Replace the per-field swaggertype tags on json.RawMessage with a single
.swaggo replace so future raw JSON fields get the same treatment. The
generated swagger.json is unchanged.

Part of DOCS-1122.

Assisted-by: AI
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The .swaggo thread is fixed in fcebe8e: replace encoding/json.RawMessage object now covers every raw JSON field, the PR's per-field tags are gone, and regenerating the docs reproduces the committed output. The PR body now describes a different change, so it needs to be restored. Findings: 1 P3, 3 P4.

Out of scope (needs a ticket or explicit acceptance by a human):

  • codersdk/audit.go:261: AuditLog.AdditionalFields and codersdk/oauth2.go:565,673,761 keep swaggertype:"object", which the new .swaggo rule makes redundant, so the code shows two mechanisms for the same schema and suggests new fields still need the tag.
  • coderd/coderdtest/swagger_test.go:59: nothing fails when a new []byte field lacks swaggertype:"string" format:"byte", so it renders as an integer array; 3 of 4 such fields were untagged before this PR. TestSDKFieldsFormatted already asserts format tags for UUID and time fields and could assert this too.
  • .swaggo:9: the existing NullUUID and NullTime comments restate their replace lines instead of giving the reason.

In reply to IC_kwDOGkVX1s8AAAABgqCzkQ:

P3 [CRF-19] The PR body describes a different change, not this diff. (Netero)

The body lists idpsync organization path parameters, format(uuid) on ids query arrays, x-example header extensions, and a TestEndpointsDocumented check; git diff 2255794d65..HEAD | grep -ciE 'idpsync|x-example|TestEndpointsDocumented|format\(uuid\)' prints 0. Reviewers and the squash commit message would describe changes this PR does not contain. Restore the round 2 body and update it for fcebe8e: json.RawMessage now renders as object through the .swaggo rule, not per-field tags.

🤖

In reply to IC_kwDOGkVX1s8AAAABgqCzkQ:

P4 [CRF-23] The title says "with their real Swagger types", but object is not the real type of result, output, or default. (Leorio)

The title becomes the squash commit subject, and codersdk/chats.go:564 says the value "can be any JSON value". For example: fix: document raw JSON as objects and byte fields as base64 strings.

🤖

🤖 This review was automatically generated with Coder Agents.

Comment thread .swaggo Resolved
Comment thread codersdk/templatebuilder.go Resolved
@nickvigilante nickvigilante changed the title fix: document raw JSON and byte fields with their real Swagger types fix: document raw JSON as objects and byte fields as base64 strings Oct 29, 2026
@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Commit 8677a48 applies the .swaggo and Default comment fixes, and the title and body now describe this diff. Regenerating the docs reproduces the committed output. One P4 remains.


In reply to IC_kwDOGkVX1s8AAAABgqSKuQ:

P4 [CRF-26] The PR description says TemplateBuilderModuleVariable.default "can hold any JSON value", but the new comment at codersdk/templatebuilder.go:27 says it is a JSON string, number, or boolean. (Leorio)

TemplateBuilderVariableType has only string, number, and bool (codersdk/templatebuilder.go:18-20), so the comment is correct and the description is the one to change. For example: "ChatMessagePart.result and ToolResult.output can hold any JSON value, and TemplateBuilderModuleVariable.default holds a string, number, or boolean, so object is an approximation for all three and the field comments say so."

🤖

🤖 This review was automatically generated with Coder Agents.

@nickvigilante

Copy link
Copy Markdown
Collaborator Author

/coder-agents-review

@coder-agents-review coder-agents-review Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The PR description now matches the Default field comment, and no new findings were raised at 8677a48. All in-scope findings from earlier rounds are resolved. The out-of-scope items listed in earlier reviews still need a ticket or explicit acceptance by a human.

🤖 This review was automatically generated with Coder Agents.

@nickvigilante
nickvigilante merged commit 585485c into main Nov 5, 2026
37 checks passed
@nickvigilante
nickvigilante deleted the fix-swagger-json-types branch November 5, 2026 18:15
@github-actions github-actions Bot locked and limited conversation to collaborators Nov 5, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

api Area: HTTP API

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants