[Metafields] admin.metafields.options.data target

[philmongeon]

Background

Part of the dynamic metafield options initiative, which lets an app supply live, presentation-only options for its own metafield definitions in Admin's native metafield editors — without persisting a choices validation that goes stale, and without rebuilding the editor as custom app UI.

Today, apps can create metafield definitions but can't influence how merchants fill them. Anything dynamic (a live catalogue, an ERP list, an external taxonomy) has to be frozen into choices validations or rebuilt as a custom UI. The new runnable target closes that gap: the app returns option lists, and Admin keeps rendering, validating, and saving.

Related work:

• Core target registration (MetafieldDynamicOptionsData schema group, internal: true, minimum_api_version: 2026-10): shop/world#983629
• Admin-web prototype + app-ownership scoping at the sandbox boundary: shop/world#949756
• Target name follows the playbook grammar admin.<area>.<thing>.data — admin.metafields.options.data Target strings are permanent, so this was settled before publishing.

Solution

Declares the client contract for admin.metafields.options.data:

• MetafieldOptionsApi — extends StandardApi with data: MetafieldOptionsData, carrying the owner resource being edited (global ID + owner type; id is null for unsaved resources) and metafields, the definitions Admin is rendering. Only definitions owned by the calling app are ever included — enforced in Core at the sandbox boundary, asserted by tests in shop/world#949756.
• MetafieldOptionsOutput — {metafields: [{namespace, key, options}]}: option lists keyed by namespace/key. Options are presentation guidance only: not persisted as choices validations, no change to save-time enforcement, a saved value stays visible if the provider stops returning it, and entries for definitions not in data.metafields are ignored. Supported definition types: single_line_text_field and list.single_line_text_field.
• Target is marked @private while Core gates it to Shopify-owned apps.

Also adds a createMetafieldOptionsMock factory (plus test) in ui-extensions-tester, whose factory map requires an entry per target.

Includes a minor changeset for @shopify/ui-extensions.

🎩

• Target compiles and type-checks against the Core schema group registered in shop/world#983629
• Verified end-to-end via the tophat app in shop/world#949756 (currently using a target alias until this lands and Core deploys)

Checklist

• I have 🎩'd these changes (blocked on Core deploy of shop/world#983629)
• I have updated relevant documentation (inline @publicDocs on all new types; target itself is @private while gated)

Notes for reviewers:

• Opened as a draft. Merge order matters: Core registration (#983629) must deploy before any app config can validate this target.
• Based on 2026-07 because no 2026-10 branch has been cut yet — may need to be retargeted once one exists.
• Open decision flagged in the Core PR: the 2026-10 API version floor (currently validates only on unstable).

[github-actions]

This PR targets a stable release branch (2026-07). Once merged, the change typically also needs to be forward-ported to 2026-10-rc so it ships in the next release.

When you open the forward-port PR, include a line like this in its body so the needs-rc-port label gets removed automatically when that PR merges:

Forward-port of #4609

Accepted formats (comma-separated for multiple):

• #4609
• GH-4609
• 4609
• https://github.com/Shopify/ui-extensions/pull/4609

If a forward-port isn't needed (e.g., the change is stable-only), you can remove the needs-rc-port label manually.