Rename tag fields from metadata to tags

[sjmiller609]

Summary

• rename user-facing tag fields from metadata to tags across OpenAPI, generated OAPI types, API handlers, and domain structs
• update tag helper/type/error naming in lib/tags to use Tags and ErrInvalidTags
• update tests and call sites to use Tags consistently

Notes

• no backward-compatibility fallbacks were added
• this PR is intended to be a pure rename for the tags feature
• addresses @rgarcia comment here Tags #127 (comment)

Validation

• make oapi-generate
• go test ./lib/tags ./lib/images ./lib/snapshot ./lib/volumes ./lib/ingress ./lib/oapi -run TestDoesNotExist

---

Note

Medium Risk
Medium risk because it is an API contract change (request/response fields and query params move from metadata to tags) with no backward-compatibility, which can break existing clients and persisted JSON expectations.

Overview
Renames the user-facing tagging contract from metadata to tags across the system. API request/response payloads and list filters now use tags (including deepObject query params like ?tags[team]=...), and CreateBuild multipart parsing switches from metadata to tags.

Domain/resource structs and on-disk JSON representations are updated to store tags instead of metadata for builds, devices, images, ingresses, instances, snapshots, and volumes; validation/cloning/matching helpers in lib/tags are renamed accordingly (including ErrInvalidTags). Tests and generated lib/oapi types/spec are updated to match the new field names, with no compatibility shim for the old metadata fields.

^{Written by Cursor Bugbot for commit 2b02226. This will update automatically on new commits. Configure here.}

[github-actions]

✱ Stainless preview builds

This PR will update the hypeman SDKs with the following commit message.

feat: Rename tag fields from metadata to tags

✅ hypeman-openapi studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅

⚠️ hypeman-typescript studio · code

Your SDK build had at least one "error" diagnostic.
generate ❗ → build ✅ → lint ✅ → test ✅

npm install https://pkg.stainless.com/s/hypeman-typescript/e2ce0c62c14252dcb12c81a4dec69a7a247b6dc6/dist.tar.gz

✅ hypeman-go studio · code

Your SDK build had at least one "note" diagnostic.
generate ✅ → build ⏭️ → lint ✅ → test ✅

go get github.com/stainless-sdks/hypeman-go@2f8e29e033b44a8a492ec9a3bdcbc44cabf2eb11

---

This comment is auto-generated by GitHub Actions and is automatically kept up to date as you push.
If you push custom code to the preview branch, re-run this workflow to update the comment.
Last updated: 2026-03-09 19:17:25 UTC

[sjmiller609]

taking liberty to merge because it's just a naming-related follow up from another PR with no functional changes

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

[cursor]

JSON tag rename silently drops persisted tags data

High Severity

Changing the JSON struct tag from json:"metadata,omitempty" to json:"tags,omitempty" on all on-disk storage structs (buildMetadata, imageMetadata, storedIngress, volume storedMetadata, Snapshot, and instance StoredMetadata) means existing JSON files persisted with the "metadata" key will silently fail to deserialize into the new Tags field. Any resources that previously had tags will lose them after this update with no error or warning. The same applies to the instance StoredMetadata struct which has no explicit JSON tags — the field rename from Metadata to Tags changes the default key. This is not a "pure rename" as the PR describes; it's a breaking on-disk format change causing silent data loss.

Additional Locations (2)

• lib/volumes/storage.go#L30-L31
• lib/snapshot/types.go#L24-L25

 

[cursor]

Risk assessment: Medium-High.

Evidence from the code diff:

• User-facing API contract changes in openapi.yaml rename schema/property names from metadata to tags across multiple request/response models.
• Corresponding generated API surface in lib/oapi/oapi.go and request handling/domain structs in cmd/api/api/* and lib/* are updated broadly.
• This is a cross-cutting production change across builds/devices/images/instances/snapshots/volumes with no compatibility shim for existing metadata clients.

Decision:

• Review is required.
• I did not approve this PR.
• Requested reviewers: rgarcia, hiroTamada.

---