Metafield definitions
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
namespace.key. - 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.
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).
POST /admin/api/unstable/graphql.json
Variables
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.
POST /admin/api/unstable/graphql.json
Variables
Retrieve a metafield definition
You can retrieve a metafield definition by using its ID, as shown in the following example.
POST /admin/api/unstable/graphql.json
JSON response
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.
POST /admin/api/unstable/graphql.json
Variables
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.
POST /admin/api/unstable/graphql.json