Metafield definitions as an API contract

A metafield can exist with no definition behind it. Shopify is direct about what that gets you: without definitions, "metafields are untyped strings that can't be edited in the Shopify admin or validated." The value is there, the API can read it, and nobody in the business can touch it or trust it.

This is how most stores acquire their first data problem. An integration writes inventory.lead_time_days as a string because that was the quickest way to get the number onto the product. Two years later nobody remembers whether the value is days or weeks, half the products have it and half do not, an ops manager who needs to correct one cannot, and the only system that can fix it is the integration that has since been replaced.

A definition converts that into something the business owns. It declares a type, so the value is number_integer and not "probably a number". It carries validation rules, so out-of-range values are rejected at the boundary rather than found later on a storefront. It makes the field editable and visible in the admin to the people who should be editing it. And it makes the field addressable by everything else on the platform — themes, automations, collection conditions — instead of being a private note the integration left behind.

The mutable half is the policy: name, description, validation rules, access settings, capabilities such as admin filtering, and constraints. This is the part designed to evolve, and two of the changes have consequences worth planning for.

Tightening validations is a data migration in disguise. Shopify notes that "tightening validations may fail if existing metafields violate the new constraint", and that the update mutation returns a validationJob — "the asynchronous job updating the metafield definition's validation_status". So adding a maximum length to a field with two thousand existing values is not an instant change; it is a request that runs, and can find non-conforming data. Check before you apply, not after.

Creating a definition over existing data has the same shape from the other direction. metafieldDefinitionCreate "validates any existing unstructured metafields matching the same owner type, namespace, and key against it", updating each valid metafield's type to match while invalid ones remain unchanged and must conform when next updated. That is a useful property — you can retrofit governance onto ungoverned fields — and it means the first definition you add to a legacy namespace tells you how bad the data is. Run it deliberately and read the result.

Shopify describes namespaces as "logical containers that not only provide organization and prevent naming conflicts, they establish ownership". That last clause is the part teams skip, and it is the part that decides whether the model holds up.

A reserved, app-owned namespace — $app in GraphQL, rendered as app--{appId}--{namespace} — marks data an app controls. Shopify's framing: "App-owned metafields are custom data entries controlled by your app. Your app manages both the structure and values, which are view only in the Shopify admin (by default)." Merchant access can be widened to merchant_read_write where it should be, but the default is that the app owns the field and humans read it.

That default is right far more often than it feels. If an integration computes a value — a lead time derived from an ERP, a risk flag, a computed margin band — then a merchandiser editing it in the admin has not fixed anything; they have introduced a value the next sync will overwrite, and an afternoon of confusion about why. App ownership makes the read-only relationship explicit instead of hoping.

The mirror of this is that merchant-owned data should live in merchant namespaces and be genuinely editable. The failure we see most often is an agency or an internal team putting editorial copy — care instructions, sizing notes, sustainability claims — inside an app-reserved namespace because that is where the build script happened to put it. The content team then cannot edit their own words, and files a ticket every time a comma changes. The namespace was wrong, and the namespace cannot be changed.

Before inventing a namespace at all, check whether Shopify already publishes a standard definition for what you are storing. Standard definitions reserve specific namespace and key pairs for common cases, and Shopify's reason for them is interoperability: they are "interoperable across the entire Shopify platform and connect more seamlessly to themes." A custom field that duplicates a standard one is a field no third-party theme or app will ever find.

If a definition is an interface, the same rules apply that you would apply to any other interface: it is declared in code, reviewed before it lands, and deployed as a versioned change. On Shopify that means defining metafields in app configuration or a migration script rather than by hand in the admin, so the schema for a store is a file someone can read, diff and roll back.

The platform pushes you this way whether you plan for it or not. Shopify documents that "you can't make more than 25 metafield changes (creation, update, or deletion) in a single deploy", which turns any large schema change into a staged sequence. That limit is a nuisance if you discover it mid-deploy and a useful constraint if you planned for it: twenty-five is roughly the size of a change a person can review properly.

The other number to keep in view is 128 metafield definitions per owner type. For a governed catalogue that is a lot of headroom. For an ungoverned one it is reachable inside two years, because ungoverned catalogues do not accumulate 128 useful fields — they accumulate forty useful fields and three near-duplicates of each, one per team that needed it and did not know the others existed.

This is also where custom back-end work earns its place. The definitions are the boundary between Shopify and everything else you run, so the same discipline that governs an internal API — owners, review, versioned change, a deprecation path — is what a [custom app or back-end integration](/services/integrate/custom-shopify-apps-and-back-ends) should bring to them. An integration that writes to fields nobody declared is not an integration, it is a leak.

• Custom Shopify apps and back ends
• Product data governance: who is allowed to change what
• Metaobjects at scale: when content modelling becomes a system