Support for Custom App-Reserved Namespaces in Declarative Metafield Definitions

Custom Data
1

Shopify’s new declarative custom data definitions are a great improvement for managing metafields and metaobjects across multiple shops. However, there is a limitation when it comes to app-reserved namespaces for metafields.

Currently, the only supported app-reserved namespace in the TOML configuration is app (which maps to $app in the API). This means all app-scoped metafields must use the $app namespace, and it is not possible to use sub-namespaces such as $app:feature-x or $app:my-custom-namespace.

Problem

Many apps, especially those with multiple features or complex configuration needs, rely on sub-namespaces to organize their metafields. For example, in the Admin API or UI Extensions, it is common to use a namespace like $app:feature-x and a key like configuration:

// In an Admin UI extension
applyMetafieldsChange([
  {
    namespace: "$app:feature-x",
    key: "configuration",
    type: "updateMetafield",
    value: JSON.stringify({ setting: "value" }),
    valueType: "json",
  },
]);

However, the TOML configuration only allows:

[resource_type.metafields.app.configuration]
type = "json"
# ...

This maps to namespace: "$app", key: "configuration".
There is no way to declare a metafield with namespace: "$app:feature-x" in TOML, and using colons or dashes in the TOML block name is not supported.

Impact

  • Organizational Limitation: Apps cannot logically group metafields by feature or module using sub-namespaces.
  • Migration Friction: Existing apps using sub-namespaces in the API cannot migrate to declarative definitions without changing their data model and code.
  • Potential for Key Collisions: All app-scoped metafields must use the same namespace, increasing the risk of key collisions as the app grows.

Request

Please add support for custom app-reserved sub-namespaces in declarative metafield definitions.
For example, allow the following TOML syntax:

[resource_type.metafields.app.feature_x.configuration]
type = "json"
# ...

which would map to namespace: "$app:feature_x", key: "configuration".

Alternatively, provide a documented and supported way to declare and use sub-namespaces for app-scoped metafields in the TOML configuration.

Example Use Case

Suppose an app has two features, “feature_x” and “feature_y”, each with its own configuration:

// Desired metafields
namespace: "$app:feature_x", key: "configuration"
namespace: "$app:feature_y", key: "configuration"

Current workaround:
The only option is to use the key to encode the feature, e.g. key: "feature_x_configuration", but this is less clean and breaks existing integrations.

1 Like
2

Hi – thanks for reaching out. Am pleased to share that this is possible today. You can create a metafield definition like the below:

[product.metafields.feature_x.configuration]
type = "single_line_text_field"

And it will be accessible under owner type: Product, key: configuration, namespace: $app:feature_x . I think that covers what you mentioned.

We’ll try to get this called out better in the docs.

1 Like
3

Hey thanks! I will try this out. Indeed would be great if you can highlight this in the docs.