# Create a metafield definition

> Create a typed, validated metafield definition with metafieldDefinitionCreate, pin it in the admin and expose it to the Storefront API.

Page: https://lintelagency.com/resources/graphql/create-metafield-definition

## In short

To create a metafield definition, call metafieldDefinitionCreate with name, namespace, key, ownerType and type, plus optional validations, access and pin. The definition gives the metafield a fixed type, an editor in the Shopify admin and rules such as a list of allowed values. Set access.storefront to PUBLIC_READ when a headless storefront needs to read it through the Storefront API.

## Facts

- **API:** Admin GraphQL API
- **Operation:** metafieldDefinitionCreate
- **Replaces (REST):** None; definitions are GraphQL only
- **API version:** 2026-10
- **Last checked:** 2 November 2026

## How to use it

1. Pick the owner type (PRODUCT here), a namespace and key, and one of Shopify’s metafield types.
2. Add validations if you need them, for example choices for a fixed list of values. Validation values are strings, so a list is a JSON array in a string.
3. Set access.storefront to PUBLIC_READ if a headless storefront reads the value, and pin: true to show it on the product page in the admin.
4. Send CreateFabricDefinition and check userErrors; TAKEN means a definition with that namespace and key already exists.

## Code

### metafield-definition-create.graphql

```graphql
mutation CreateFabricDefinition($definition: MetafieldDefinitionInput!) {
  metafieldDefinitionCreate(definition: $definition) {
    createdDefinition {
      id
      namespace
      key
      name
      ownerType
      type {
        name
      }
      validations {
        name
        value
      }
      access {
        storefront
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}
```

### metafield-definition-create.variables.json

```json
{
  "definition": {
    "name": "Fabric",
    "namespace": "custom",
    "key": "fabric",
    "description": "Main fabric, shown on the product page and used as a filter.",
    "ownerType": "PRODUCT",
    "type": "single_line_text_field",
    "validations": [
      {
        "name": "choices",
        "value": "[\"Cotton\",\"Linen\",\"Wool\"]"
      }
    ],
    "access": {
      "storefront": "PUBLIC_READ"
    },
    "pin": true
  }
}
```

### metafield-definition-create.response.json

```json
{
  "data": {
    "metafieldDefinitionCreate": {
      "createdDefinition": {
        "id": "gid://shopify/MetafieldDefinition/1234567890",
        "namespace": "custom",
        "key": "fabric",
        "name": "Fabric",
        "ownerType": "PRODUCT",
        "type": {
          "name": "single_line_text_field"
        },
        "validations": [
          {
            "name": "choices",
            "value": "[\"Cotton\",\"Linen\",\"Wool\"]"
          }
        ],
        "access": {
          "storefront": "PUBLIC_READ"
        }
      },
      "userErrors": []
    }
  }
}
```

## Limits and edge cases

- Existing metafields with the same owner type, namespace and key are checked against the new definition. Valid ones take its type; invalid ones keep their value but must match the definition the next time they’re saved.
- Leaving out namespace uses your app’s reserved namespace. Definitions under it are owned by your app.
- A definition can’t change its type later; create a new key if the type was wrong.
- The number of pinned definitions per owner type is limited; PINNED_LIMIT_REACHED in userErrors means you hit it.

## Questions

### What is the difference between a metafield and a metafield definition?

A metafield is a value on one resource. A definition describes the namespace and key for all resources of a type: its type, validation, admin editor and API access.

### Why can’t I read my metafield with the Storefront API?

Its definition needs storefront access set to PUBLIC_READ. With NONE, the Storefront API can’t read the value.

### Can I restrict a metafield to a list of values?

Yes. Add a choices validation with a JSON array of allowed values; the admin then shows a dropdown and the API rejects other values.

## Shopify documentation

- [metafieldDefinitionCreate](https://shopify.dev/docs/api/admin-graphql/latest/mutations/metafieldDefinitionCreate)
- [Metafield definitions](https://shopify.dev/docs/apps/build/custom-data/metafields/definitions)

## Related

- [Write metafields with metafieldsSet](https://lintelagency.com/resources/graphql/metafields-set)
- [Read metafields and metaobjects with the Storefront API](https://lintelagency.com/resources/graphql/storefront-metafields-and-metaobjects)
- [Configuring Functions with metafields, so rules change without deploys](https://lintelagency.com/journal/configuring-functions-with-metafields)

License: MIT. Free to use in your own store and in client work.