docs: document credentialFile.structure support - #25786
Conversation
5f87b5f to
6c523e4
Compare
dvdksn
changed the title
The kit reference marked credentialFile.structure as unsupported even though Docker Sandboxes 0.39.0 implements its runtime rendering. Update the OAuth example and field reference to document structure alongside template, including typed JSON output and precedence when both fields are set.
6c523e4 to
1f169e1
Compare
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🔴 CRITICAL
One high-severity and one medium-severity issue found in the new credentialFile.structure documentation.
The placeholder descriptions overexplained implementation distinctions and made the reference difficult to scan. List the supported placeholders directly and keep the behavior explanation focused on rendered JSON and precedence.
27847a6 to
a36eded
Compare
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
The changes accurately document credentialFile.structure support alongside credentialFile.template. The YAML example is updated correctly, the table rows reflect the right precedence rule, and the placeholder syntax ({{.Scopes}} / {{.ExpiresAt}} as quoted strings) is intentional and correct — the runtime replaces those YAML strings with native typed values before JSON encoding. No style guide violations, vendored content, missing redirects, or broken markdown found.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
| | `credentialFile.template` | Go template used to render the credential file. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, `{{.Scopes}}`, and `{{.ScopesJSON}}`. Use `{{.ScopesJSON}}` for a JSON array. | | ||
| | `credentialFile.structure` | Declarative JSON shape defined by schema v2 but not supported by the `sbx` engine. A structure-only kit fails validation. Use `credentialFile.template`. | | ||
| | `credentialFile.structure` | Declarative JSON shape. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, and `{{.Scopes}}`. | | ||
| | `credentialFile.template` | Go template. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, `{{.Scopes}}`, and `{{.ScopesJSON}}`. | |
There was a problem hiding this comment.
[MEDIUM] Guidance on using {{.ScopesJSON}} for JSON array in template removed
The previous credentialFile.template description included: "Use {{.ScopesJSON}} for a JSON array." That hint is now gone.
In template context, {{.Scopes}} renders as a Go slice ([scope1 scope2]), which is not valid JSON. {{.ScopesJSON}} renders as a proper JSON array (["scope1","scope2"]). Without this guidance, a user writing a JSON credential file using template who reaches for {{.Scopes}} (which is now listed in both fields' descriptions) will produce malformed JSON.
Consider restoring the distinguishing note, for example:
| `credentialFile.template` | Go template. Supports `{{.AccessToken}}`, `{{.RefreshToken}}`, `{{.ExpiresAt}}`, `{{.Scopes}}`, and `{{.ScopesJSON}}`. Use `{{.ScopesJSON}}` to render scopes as a JSON array. |
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
| accessToken: "{{.AccessToken}}" | ||
| refreshToken: "{{.RefreshToken}}" | ||
| expiresAt: "{{.ExpiresAt}}" | ||
| scopes: "{{.Scopes}}" |
There was a problem hiding this comment.
[MEDIUM] Quoted {{.Scopes}} placeholder in YAML example is misleading without explanation of array promotion
The example shows scopes: "{{.Scopes}}" as a quoted YAML string, but the runtime promotes this value to a native JSON array before encoding. A kit author reading the example would naturally expect a JSON string for scopes and might reach for {{.ScopesJSON}} (which the table correctly notes is only supported by template, not structure) or manually construct a YAML sequence — both of which would produce a broken configuration.
Consider adding a brief note near the example or in the prose paragraph below the table explaining that when a structure value consists solely of a placeholder, the runtime replaces it with the native typed value: expiresAt becomes a JSON number and scopes becomes a JSON array.
| | `responseFields` | Overrides the default field names the proxy reads from the token response. | | ||
| | `passthrough` | If `true`, the proxy passes the token response through unchanged instead of replacing the tokens with sentinels. | | ||
|
|
||
| `credentialFile.structure` provides a declarative alternative to |
There was a problem hiding this comment.
[MEDIUM] No explanation of typed JSON promotion for quoted structure placeholders
The prose states "The engine renders it as well-formed JSON" but does not explain the runtime's typed-promotion behavior: when a structure value consists only of a placeholder (e.g., "{{.ExpiresAt}}"), the engine replaces the YAML string with the native typed value before JSON encoding — so expiresAt becomes a JSON number and scopes becomes a JSON array, not JSON strings.
Without this explanation, readers who see quoted-string placeholders in the YAML example have no way to understand the resulting JSON shape. A single clarifying sentence here (or a > [!NOTE] callout) would close the gap.
3 participants
Summary
Update the kit spec reference for Docker Sandboxes v0.39.0 to document
credentialFile.structurealongsidecredentialFile.template. Show the declarative structure form in the OAuth example and document its supported placeholders, typed JSON output, and precedence when both fields are set, as implemented by docker/sandboxes#4830.@netlify /ai/sandboxes/customize/kit-reference/
Preview the updated kit spec reference
Generated by Codex