| name | sync-schema-descriptions |
| description | Sources Terraform schema descriptions from the pinned oxide.go SDK's Go doc
comments, which already mirror the OpenAPI spec. Adapts the text to the TF
surface (translating reshaped attribute names, clarifying NameOrId inputs,
trimming API-internal paragraphs, and reconciling any divergence between
provider and API default behavior) so the descriptions stay accurate and
aligned with the version of the SDK the provider actually calls into.
|
Sync Schema Descriptions
Overview
Terraform schema Description / MarkdownDescription strings are hand-written
and drift from the canonical descriptions in the OpenAPI spec. The oxide.go
SDK, pinned via go.mod, has the same descriptions baked into Go doc comments
on each field. This skill walks through sourcing the right description,
adapting it, and applying the change.
Not every TF attribute maps 1:1 to a single SDK field (e.g. TF's boot_disk_id
corresponds to the SDK's richer boot_disk), so blind copying is wrong. The
skill codifies the adaptation process rather than automating it blindly.
Workflow
1. Resolve the SDK source
go list -m -f '{{.Dir}}' github.com/oxidecomputer/oxide.go
Descriptions live in <dir>/oxide/types.go. Do not use a local checkout of
the SDK, which might not match the pinned version.
2. Identify scope
The user will usually ask about one attribute (e.g. instance.ssh_public_keys),
a whole resource, or all resources. For each in-scope attribute, work through
steps 3–8.
3. Locate the TF attribute
In internal/provider/<resource>/resource.go (or data_source.go), find the
schema block and note the current Description / MarkdownDescription. Find
the TF model struct field via its tfsdk:"<attr_name>" tag.
Do not touch schema-version-compat files (resource_v0.go, resource_v1.go,
…). They represent frozen prior schemas kept for state upgrades; descriptions
there are not rendered to current docs, so the files should stay as they
were when that version shipped.
4. Find the matching SDK field
Input attributes (set in Create/Update): grep the Create method for the
model field. You'll see a line like params.Body.SshPublicKeys = .... The SDK
struct is the type of params.Body (e.g. oxide.InstanceCreate); the SDK
field is the LHS accessor.
Computed/output attributes (populated in Read): grep the Read method for
how state.<Field> is set from the API response — e.g.
state.TimeCreated = types.StringValue(resp.TimeCreated.String()). The SDK
struct is the response type (e.g. oxide.Instance), the field is the resp.<X>
accessor.
If the TF attribute has no clean 1:1 SDK counterpart (flattened, split, or
composed from multiple API fields), stop and surface this to the user — it
needs a hand-written description, not an adaptation.
5. Read the SDK doc comment
Open <sdk_dir>/oxide/types.go, find type <StructName> struct, and read the
Go doc comment on the field. Comments are hard-wrapped; reflow them into a
single logical description.
Also note the field's Go type — it drives adaptation rule (b) below.
6. Adapt
The default is verbatim. Copy the SDK doc comment's prose into the TF
description word-for-word. Do not insert em dashes, merge sentences,
paraphrase verbs, or restructure for flow. The value of sourcing from the SDK
is fidelity to a single maintained source of truth; editorial drift
reintroduces exactly the hand-written divergence the skill is meant to
eliminate.
Only deviate when one of the rules below applies, and only to the extent the
rule requires. If you aren't sure whether a change is required, keep the
source wording and ask the operator.
Do not invent text from sibling attributes. If the SDK has no usable
description for a given TF attribute (e.g. the SDK doc comment is a
tautology like "X is a variant of Y", or the corresponding SDK type/field is
internal wrapping with no prose), the skill's job is done — the attribute
needs a hand-written description, which is outside this skill's scope.
Surface the gap to the operator. Never copy text from a TF sibling
(v4 → v6, ephemeral → floating, etc.) and pass it off as adapted; it
is still hand-written, just plagiarized.
a. Translate field-name references. If the comment references an API field
name that differs in TF (e.g. "set the boot_disk attribute"), rewrite it to
the TF name (boot_disk_id). Same for any other cross-referenced field.
b. NameOrId phrasing. The API accepts both names and IDs for
NameOrId / []NameOrId inputs. The right phrasing depends on what the TF
attribute represents:
- If the attribute is the resource's own
name (typically a required
top-level attribute on a resource or data source), it stores the name.
Describe as "Name of …".
- If the attribute is a reference to another resource (e.g.
vpc_id,
disk_attachments, boot_disk_id), the provider writes the resolved ID
back into state on Read, so a user who supplies a name will see a
perpetual diff (or recreate) on the next plan. Until the provider
preserves the user-supplied form, keep descriptions honest: say "ID of
…" / "IDs of …" regardless of whether the SDK field type is string or
NameOrId. If the source SDK comment says "name or ID", rewrite to "ID".
c. Trim non-user-facing paragraphs. Drop:
- internal API behavior the TF user can't observe
- roadmap/hedging language ("currently, …", "in the future, …")
- information already encoded by the TF schema (e.g. defaults — TF renders
those separately)
Keep paragraphs describing user-visible behavior: accepted value forms,
interactions with other attributes. Paragraphs about omission/defaults need
verification first — see rule (e).
d. Preserve TF-specific additions. If the current TF description contains
information that isn't in the SDK (e.g. cross-refs to other TF attrs, validator
behavior), keep it — it usually reflects provider logic that doesn't exist at
the API level.
e. Provider defaults may diverge from API defaults. Any SDK phrase like
"if not provided, …", "if null, …", or "defaults to …" describes what the
API does when the field is absent from the request — but the provider may
not actually omit the field. Helpers like shared.NewNameOrIdList return
[]T{} (never nil), and whether that serializes as [] or gets dropped
depends on the SDK struct's JSON tag (omitempty / omitzero vs. bare). An
empty list reaching the API is semantically different from an absent field.
If the SDK description includes a default-behavior clause, decide how to
handle it:
- Inspect the code. Trace the provider's Create/Update path for the field
and confirm whether a null TF value produces an omitted request field or a
zero-value one. If the provider's behavior matches the SDK clause, keep it;
if it doesn't, rewrite to describe what the provider actually does.
- Ask the operator. If the behavior isn't clear from the code, or if the
mismatch looks like a provider bug worth fixing separately, surface it.
- Omit the clause. When in doubt, drop the default-behavior sentence
entirely rather than risk a misleading description.
f. Add undocumented TF-specific constraints. Rule (d) is about keeping
what's already in the current description; this rule is about adding what's
missing. If the schema has validators or plan modifiers whose effect isn't
mentioned in the current description, fold a short clause in — the
framework's auto-generated docs don't surface these. Examples:
stringvalidator.LengthBetween(1, 63) → "Must be 1–63 characters."stringvalidator.RegexMatches(pattern, "…") → reuse the validator's
message, or describe the pattern.stringvalidator.OneOf("a", "b", "c") → "Must be one of a, b, c."
Skip constraints the framework already renders (Required / Optional /
Computed flags, Default values — same reasoning as rule (c)).
7. Apply, then hand off for review
Apply all proposed changes with Edit to the current resource.go /
data_source.go only (never resource_v*.go). Run make fmt to regenerate
docs/resources/*.md and docs/data-sources/*.md, then make lint to verify.
Report what was changed in a short summary and tell the operator to review via
git diff. The diff is a better review surface for multi-attribute text
changes than an in-chat bulleted list.
8. Show the provenance table
At the end of the pass, emit a table with one row per touched attribute:
| Attribute | SDK source (field, verbatim) | Provider description (as applied) |
For each row:
- SDK source: the type + field (e.g.
InstanceCreate.Memory) and the
doc-comment prose as it appears in oxide/types.go, unedited. For rule (f)
additions, use "(none — rule f)" and name the validator.
- Provider description: the final string now in the schema, so the
operator can see the adaptation deltas inline without chasing through
git diff and the SDK side-by-side.
One row per attribute updated — skip attributes left untouched.
Exceptions — pause and surface to the operator before editing rather than
after:
- Step 4 found no clean 1:1 SDK counterpart (reshaped, split, or composed
attribute) — the description needs to be hand-written, not adapted.
- Rule (e) flagged a behavior-claim mismatch that implies a provider fix is
needed rather than a description change. Describe the mismatch and ask
whether to narrow the description to match current provider behavior or open
a separate issue to fix the provider first.
Notes
- The SDK pins to a specific Omicron release; the descriptions on disk match
the API the provider actually calls at runtime. There is no need to fetch
the OpenAPI spec directly.
- When
go.mod bumps oxide.go, upstream descriptions may change. Re-running
this skill after an SDK bump is a reasonable drift-detection pass.
