<!-- Extension API v0 — pre-1.0. Interfaces may change without notice until P2 seals the custom-code format. First-party extensions track HEAD. -->

# `metafield.definition.create`

Define a typed custom field on products, variants, collections, or the store.

- **scope**: `store:admin`
- **storefront-visible** (bumps the catalog generation): no
- **destructive**: no

## Payload

| field | type | required | notes |
|---|---|---|---|
| `ownerType` | "product" \| "variant" \| "collection" \| "store" | yes |  |
| `namespace` | string (/^(custom\|app\.[a-z0-9-]{2,32})$/) | yes |  |
| `key` | string (/^[a-z0-9_]{1,64}$/) | yes |  |
| `valueType` | "text" \| "integer" \| "decimal" \| "boolean" \| "date" \| "json" | yes |  |
| `labelTR` | string (≤100 chars) | yes |  |
| `descriptionTR` | string (≤500 chars) | no |  |
| `validations` | object | no |  |
| `  min` | number | no |  |
| `  max` | number | no |  |
| `  maxLength` | integer (..65536) | no |  |
| `  regex` | string (≤200 chars) | no |  |
| `  choices` | array<string (≤100 chars)> (≤50) | no |  |

### JSON Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ownerType": {
      "type": "string",
      "enum": [
        "product",
        "variant",
        "collection",
        "store"
      ]
    },
    "namespace": {
      "type": "string",
      "pattern": "^(custom|app\\.[a-z0-9-]{2,32})$"
    },
    "key": {
      "type": "string",
      "pattern": "^[a-z0-9_]{1,64}$"
    },
    "valueType": {
      "type": "string",
      "enum": [
        "text",
        "integer",
        "decimal",
        "boolean",
        "date",
        "json"
      ]
    },
    "labelTR": {
      "type": "string",
      "minLength": 1,
      "maxLength": 100
    },
    "descriptionTR": {
      "type": "string",
      "maxLength": 500
    },
    "validations": {
      "type": "object",
      "properties": {
        "min": {
          "type": "number"
        },
        "max": {
          "type": "number"
        },
        "maxLength": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 65536
        },
        "regex": {
          "type": "string",
          "maxLength": 200
        },
        "choices": {
          "minItems": 1,
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 100
          }
        }
      },
      "additionalProperties": false
    }
  },
  "required": [
    "ownerType",
    "namespace",
    "key",
    "valueType",
    "labelTR"
  ],
  "additionalProperties": false
}
```