--- title: MetafieldDefinition - GraphQL Admin description: >- Defines the structure, validation rules, and permissions for [`Metafield`](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield) objects attached to a specific owner type. Each definition establishes a schema that metafields must follow, including the data type and validation constraints. The definition controls access permissions across different APIs, determines whether the metafield can be used for filtering or as a collection condition, and can be constrained to specific resource subtypes. 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 Defines the structure, validation rules, and permissions for [`Metafield`](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield) objects attached to a specific owner type. Each definition establishes a schema that metafields must follow, including the data type and validation constraints. The definition controls access permissions across different APIs, determines whether the metafield can be used for filtering or as a collection condition, and can be constrained to specific resource subtypes. ## 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 Retrieves a [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/current/objects/MetafieldDefinition) by its identifier. You can identify a definition using either its owner type, namespace, and key, or its global ID. Use this query to inspect a definition's configuration, including its data type, validations, access settings, and the count of [metafields](https://shopify.dev/docs/api/admin-graphql/current/objects/Metafield) using it. * [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 [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/current/objects/MetafieldDefinition) that establishes structure and validation rules for metafields. The definition specifies the data type, validation constraints, and access permissions for metafields with a given namespace and key combination. When you create a new definition, the system validates any existing unstructured metafields matching the same owner type, namespace, and key against it. The system updates each valid metafield's type to match the definition. Invalid metafields remain unchanged but must conform to the definition when updated. Learn more about [creating metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions). * [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 [`MetafieldDefinition`](https://shopify.dev/docs/api/admin-graphql/current/objects/MetafieldDefinition)'s configuration and settings. You can modify the definition's name, description, validation rules, access settings, capabilities, and constraints. The mutation updates access settings that control visibility across different APIs, such as the [GraphQL Admin API](https://shopify.dev/docs/api/admin-graphql), [Storefront API](https://shopify.dev/docs/api/storefront), and [Customer Account API](https://shopify.dev/docs/api/customer). It also enables capabilities like admin filtering or unique value validation, and modifies constraints that determine which resource subtypes the definition applies to. *** Note The type, namespace, key, and owner type identify the definition and so can't be changed. *** Learn more about [updating metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions). * [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)