---
title: MetafieldDefinition - Shop Partners API
description: |-
  A MetafieldDefinition is a Permissible type. It is managed by a Client and defines the shape of the
  data stored in in a Metafield. Control and access of a MetafieldDefinition is determined by AccessGrants
  that link the definition to Clients or Namespaces.
api_version: unstable latest
source_url:
  html: https://shopify.dev/docs/api/shop-partners/latest/objects/MetafieldDefinition
  md: https://shopify.dev/docs/api/shop-partners/latest/objects/MetafieldDefinition.md
---

# Metafield​Definition

object

A MetafieldDefinition is a Permissible type. It is managed by a Client and defines the shape of the data stored in in a Metafield. Control and access of a MetafieldDefinition is determined by AccessGrants that link the definition to Clients or Namespaces.

## Fields

* access

  [Custom​Data​Access​Type](https://shopify.dev/docs/api/shop-partners/latest/objects/CustomDataAccessType)

  List of the active policies associated with this Definition. Policies represent ownership of the Definition and can be granted to Clients and Nampespaces.

* description

  [String](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

  Developer facing description.

* key

  [String!](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

  non-null

  Developer facing identifier for the resource.

* name

  [String](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

  Developer facing display name.

* namespace

  [String](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

  Developer facing path to identifier for the resource.

* type

  [Metafield​Definition​Type!](https://shopify.dev/docs/api/shop-partners/latest/objects/MetafieldDefinitionType)

  non-null

  One of the types available in the Metafield developer documentation (<https://shopify.dev/docs/apps/custom-data/metafields/types>), except JSON.

* uuid

  [ID!](https://shopify.dev/docs/api/shop-partners/latest/scalars/ID)

  non-null

  Internal identifier for the resource.

* validations

  [\[Custom​Data​Metafield​Definition​Validation​Type!\]](https://shopify.dev/docs/api/shop-partners/latest/objects/CustomDataMetafieldDefinitionValidationType)

  A list of validation options for the metafields that belong to the metafield definition.

***

## Map

### Fields and connections with this object

* [MetafieldDefinitionConnection.nodes](https://shopify.dev/docs/api/shop-partners/latest/connections/MetafieldDefinitionConnection#returns-nodes)
* [MetafieldDefinitionEdge.node](https://shopify.dev/docs/api/shop-partners/latest/objects/MetafieldDefinitionEdge#field-MetafieldDefinitionEdge.fields.node)

***

## Queries

* [metafield​Definition](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinition)

  query

  Retrieve a single metafield definition by identifier

  * identifier

    [Custom​Data​Key​Pair​Input!](https://shopify.dev/docs/api/shop-partners/latest/input-objects/CustomDataKeyPairInput)

    required

    ### Arguments

    Key and namespace pair that together form the path to the definition. Key is required, Namespace defaults to the Client's implicit, reserved namespace if not provided. Leave blank to see everything available to the client.

  ***

* [metafield​Definitions](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinitions)

  query

  List of metafield\_definitions

  * after

    [String](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

    ### Arguments

    Returns the elements that come after the specified cursor.

  * before

    [String](https://shopify.dev/docs/api/shop-partners/latest/scalars/String)

    Returns the elements that come before the specified cursor.

  * first

    [Int](https://shopify.dev/docs/api/shop-partners/latest/scalars/Int)

    Returns up to the first `n` elements from the list.

  * identifiers

    [\[Custom​Data​Key​Pair​Input!\]](https://shopify.dev/docs/api/shop-partners/latest/input-objects/CustomDataKeyPairInput)

    Default:\[]

    Key and namespace pair that together form the path to the definition. Key is required, Namespace defaults to the Client's implicit, reserved namespace if not provided. Leave blank to see everything available to the client.

  * last

    [Int](https://shopify.dev/docs/api/shop-partners/latest/scalars/Int)

    Returns up to the last `n` elements from the list.

  * reverse

    [Boolean](https://shopify.dev/docs/api/shop-partners/latest/scalars/Boolean)

    Reverse the order of the underlying list.

  * sort​Key

    [Metafield​Permissible​Sort​Keys](https://shopify.dev/docs/api/shop-partners/latest/enums/MetafieldPermissibleSortKeys)

    Default:KEY

    Sort the underlying listing by the given key.

  ***

***

## MetafieldDefinition Queries

### Queried by

* [metafield​Definition](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinition)
* [metafield​Definitions](https://shopify.dev/docs/api/shop-partners/latest/queries/metafieldDefinitions)

***

## Mutations

* [metafield​Definition​Create](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionCreate)

  mutation

  Create a new MetafieldDefinition.

  * definition

    [Metafield​Definition​Create​Input!](https://shopify.dev/docs/api/shop-partners/latest/input-objects/MetafieldDefinitionCreateInput)

    required

    ### Arguments

  ***

* [metafield​Definition​Delete](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionDelete)

  mutation

  Remove a MetafieldDefinition and cascade delete all associated Metafields.

  * identifier

    [Custom​Data​Key​Pair​Input!](https://shopify.dev/docs/api/shop-partners/latest/input-objects/CustomDataKeyPairInput)

    required

    ### Arguments

    This argument accepts an object that consists of a `key` and an optional `namespace`. The `key` is a mandatory attribute that represents a specific element within a namespace. The `namespace` attribute, if provided, should be a period-delimited string representing the hierarchical path to the desired definition. This is applicable in cases where the desired definition is nested within namespaces. In the absence of a provided `namespace`, the system will default to the client's implicit, reserved namespace.

  ***

* [metafield​Definition​Update](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionUpdate)

  mutation

  Update a MetafieldDefinition by changing its key, name, description, capabilities, or access.

  * definition

    [Metafield​Definition​Update​Input!](https://shopify.dev/docs/api/shop-partners/latest/input-objects/MetafieldDefinitionUpdateInput)

    required

    ### Arguments

  ***

***

## MetafieldDefinition Mutations

### Mutated by

* [metafield​Definition​Create](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionCreate)
* [metafield​Definition​Delete](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionDelete)
* [metafield​Definition​Update](https://shopify.dev/docs/api/shop-partners/latest/mutations/metafieldDefinitionUpdate)

***

## Interfaces

* [Custom​Data​Permissible](https://shopify.dev/docs/api/shop-partners/latest/interfaces/CustomDataPermissible)

  interface

***

## MetafieldDefinition Implements

### Implements

* [Custom​Data​Permissible](https://shopify.dev/docs/api/shop-partners/latest/interfaces/CustomDataPermissible)