--- title: MetafieldDefinition - GraphQL Admin description: |- Metafield definitions enable you to define additional validation constraints for metafields, and enable the merchant to edit metafield values in context. api_version: 2025-10 api_name: admin type: object api_type: graphql source_url: html: https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition md: https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinition.md --- # Metafield​Definition object Metafield definitions enable you to define additional validation constraints for metafields, and enable the merchant to edit metafield values in context. ## Fields * access [Metafield​Access!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldAccess) non-null The access settings associated with the metafield definition. * capabilities [Metafield​Capabilities!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldCapabilities) non-null The capabilities of the metafield definition. * constraints [Metafield​Definition​Constraints](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinitionConstraints) The [constraints](https://shopify.dev/apps/build/custom-data/metafields/conditional-metafield-definitions) that determine what subtypes of resources a metafield definition applies to. * description [String](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) The description of the metafield definition. * id [ID!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/ID) non-null A globally-unique ID. * key [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The unique identifier for the metafield definition within its namespace. * metafields [Metafield​Connection!](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldConnection) non-null The metafields that belong to the metafield definition. * metafields​Count [Int!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) non-null The count of the metafields that belong to the metafield definition. * validation​Status [Metafield​Validation​Status](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldValidationStatus) ### Arguments The current validation status. *** * name [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The human-readable name of the metafield definition. * namespace [String!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/String) non-null The container for a group of metafields that the metafield definition is associated with. * owner​Type [Metafield​Owner​Type!](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldOwnerType) non-null The resource type that the metafield definition is attached to. * pinned​Position [Int](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Int) The position of the metafield definition in the pinned list. * standard​Template [Standard​Metafield​Definition​Template](https://shopify.dev/docs/api/admin-graphql/latest/objects/StandardMetafieldDefinitionTemplate) The standard metafield definition template associated with the metafield definition. * type [Metafield​Definition​Type!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinitionType) non-null The type of data that each of the metafields that belong to the metafield definition will store. Refer to the list of [supported types](https://shopify.dev/apps/metafields/types). * use​As​Collection​Condition [Boolean!](https://shopify.dev/docs/api/admin-graphql/latest/scalars/Boolean) non-null Whether the metafield definition can be used as a collection condition. * validations [\[Metafield​Definition​Validation!\]!](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinitionValidation) non-null A list of [validation options](https://shopify.dev/apps/metafields/definitions/validation) for the metafields that belong to the metafield definition. For example, for a metafield definition with the type `date`, you can set a minimum date validation so that each of the metafields that belong to it can only store dates after the specified minimum. * validation​Status [Metafield​Definition​Validation​Status!](https://shopify.dev/docs/api/admin-graphql/latest/enums/MetafieldDefinitionValidationStatus) non-null The validation status for the metafields that belong to the metafield definition. *** ## Map ### Fields and connections with this object * {}[CollectionRuleMetafieldCondition.metafieldDefinition](https://shopify.dev/docs/api/admin-graphql/latest/objects/CollectionRuleMetafieldCondition#field-CollectionRuleMetafieldCondition.fields.metafieldDefinition) * {}[Metafield.definition](https://shopify.dev/docs/api/admin-graphql/latest/objects/Metafield#field-Metafield.fields.definition) * <->[MetafieldDefinitionConnection.nodes](https://shopify.dev/docs/api/admin-graphql/latest/connections/MetafieldDefinitionConnection#returns-nodes) * {}[MetafieldDefinitionEdge.node](https://shopify.dev/docs/api/admin-graphql/latest/objects/MetafieldDefinitionEdge#field-MetafieldDefinitionEdge.fields.node) *** ## Queries * [metafield​Definition](https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition) query Returns a metafield definition by identifier. * [metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinitions) query Returns a list of metafield definitions. *** ## \MetafieldDefinition Queries ### Queried by * \[metafield​Definition](https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinition) * \[metafield​Definitions](https://shopify.dev/docs/api/admin-graphql/latest/queries/metafieldDefinitions) *** ## Mutations * [metafield​Definition​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate) mutation Creates a metafield definition. Any metafields existing under the same owner type, namespace, and key will be checked against this definition and will have their type updated accordingly. For metafields that are not valid, they will remain unchanged but any attempts to update them must align with this definition. * [metafield​Definition​Pin](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionPin) mutation You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed. * [metafield​Definition​Unpin](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUnpin) mutation You can organize your metafields in your Shopify admin by pinning/unpinning metafield definitions. The order of your pinned metafield definitions determines the order in which your metafields are displayed on the corresponding pages in your Shopify admin. By default, only pinned metafields are automatically displayed. * [metafield​Definition​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate) mutation Updates a metafield definition. * [standard​Metafield​Definition​Enable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/standardMetafieldDefinitionEnable) mutation Activates the specified standard metafield definition from its template. Refer to the [list of standard metafield definition templates](https://shopify.dev/apps/metafields/definitions/standard-definitions). *** ## <\~> MetafieldDefinition Mutations ### Mutated by * <\~>[metafield​Definition​Create](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate) * <\~>[metafield​Definition​Pin](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionPin) * <\~>[metafield​Definition​Unpin](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUnpin) * <\~>[metafield​Definition​Update](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionUpdate) * <\~>[standard​Metafield​Definition​Enable](https://shopify.dev/docs/api/admin-graphql/latest/mutations/standardMetafieldDefinitionEnable) *** ## Interfaces * [Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node) interface *** ## ||-MetafieldDefinition Implements ### Implements * ||-[Node](https://shopify.dev/docs/api/admin-graphql/latest/interfaces/Node)