Metafield definitions enable you to create additional validation constraints for metafields, and enable the merchant to edit metafield values in context. Where possible, you should adopt standard metafields, so that your app can access information that merchants have already stored in standard metafields. You can also create your own custom metafield definitions.
If you want to create and manage metafield definitions with your app, then you can use the GraphQL Admin API as described on this page. If you're helping a merchant to build their store, and you want to set up metafields in the Shopify admin, then refer to the merchant documentation about metafields.
Structure of a metafield definition
A metafield definition includes the following information:
- Name: A human-readable name for the definition.
- Namespace and key: A namespace and key to identify and group the metafield, sorted as
- Type: The type of data that the metafield stores.
- Owner type: The resource or resources that the metafield can be attached to. For example, you could make a metafield definition that's attached to the Product resource.
- Description (optional): A description of the metafield that's shown in the Shopify admin.
- Validation options (optional): An array of validation options for the metafield. For example, for a metafield with the type
date, you can set a minimum date validation, so that the metafield can store only dates after a specific date.
- Presentation hints (optional): An array of presentation options for the metafield. Presentation hints allow merchants to define how they want certain metafields to render on their online store and other channels. For example, a presentation hint could be added to a boolean value to display
Noon the online store.
Create a metafield definition
You can create a metafield definition using the
metafieldDefinitionCreate mutation. The following example displays how to add a metafield definition called "Ingredients" to the Product resource, which stores multi-line text (such as a list of ingredients used to make the product).
Create a metafield definition with a validation option
The following example displays how to create a metafield definition called
Pizza size with a minimum size of 9 and a maximum size of 15.
Retrieve a metafield definition
You can retrieve a metafield definition by using its ID, as shown in the following example.
Update a metafield definition
To update a metafield definition, use the
metafieldDefinitionUpdate mutation. You can update only the name and description of a metafield.
In the following example, you want to change a metafield definition's name from
Pizza size to
Pizza size (inches). This name is displayed to merchants in the Shopify admin.
Delete a metafield definition
To delete a metafield definition, use the
metafieldDefinitionDelete mutation. You can also set an option that, when selected, deletes all metafields that use that definition.
The following example deletes the metafield definition for
bakery.ingredients, and also deletes all metafields that use the definition.