> ## Documentation Index
> Fetch the complete documentation index at: https://docs.launchmystore.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Metafield Definitions Overview

> Schema for metafields — type, validations, label, pinning. Admin API only.

# Metafield Definitions

A **definition** is the schema for a metafield: it sets the type,
validation rules, human label, and whether the field is pinned to the
resource detail page in admin. Values that conflict with the definition's
type or validations are rejected at write time.

<Warning>
  Definition CRUD lives on the **Admin API** (merchant JWT) only. It is
  **not** exposed to OAuth-scoped apps. Apps can write metafield *values*
  without ever creating a definition — the type+validation contract is
  optional. Definitions exist primarily to power the merchant *Settings →
  Custom data* admin UI.
</Warning>

## Why definitions exist

| Without a definition                             | With a definition                                   |
| ------------------------------------------------ | --------------------------------------------------- |
| Apps can write any type to any namespace/key     | Type is enforced at write time                      |
| No human label — admin shows the raw `key`       | Human-friendly `name`, `description`                |
| Doesn't appear in the admin "Custom data" picker | Listed in *Settings → Custom data*                  |
| Doesn't auto-show on the resource edit page      | If `pinned: true`, appears on the resource form     |
| Validation rules can't be enforced centrally     | `min`, `max`, `regex`, `choices`, etc. all enforced |

## Schema

| Field                      | Type          | Notes                                                                                              |
| -------------------------- | ------------- | -------------------------------------------------------------------------------------------------- |
| `id`                       | UUID          | server-generated                                                                                   |
| `storeId`                  | UUID          | scoped per store                                                                                   |
| `namespace`                | string        | e.g. `custom`, `my_app`, `specs`                                                                   |
| `key`                      | string        | machine name                                                                                       |
| `name`                     | string        | human label shown in admin                                                                         |
| `type`                     | enum          | one of the 22 [supported types](/api-reference/metafields/overview#supported-types-22)             |
| `owner_type`               | enum          | one of the 9 [owner types](/api-reference/metafields/overview#owner-types-nine)                    |
| `validations`              | object        | type-dependent — `min`, `max`, `regex`, `choices`, `list_min`, `list_max`, `allowed_schemes`, etc. |
| `description`              | string        | optional admin tooltip                                                                             |
| `pinned`                   | bool          | if true, appears on the resource detail edit page                                                  |
| `created_at`, `updated_at` | ISO timestamp | –                                                                                                  |

Definitions are keyed by `(owner type, namespace, key)` — one
definition per combination per store.

## Validation rules per type

The `validations` object's allowed keys depend on `type`:

| Type                            | Allowed validations                                               |
| ------------------------------- | ----------------------------------------------------------------- |
| `single_line_text_field`        | `min`, `max`, `regex`, `choices`                                  |
| `multi_line_text_field`         | `min`, `max`, `regex`                                             |
| `rich_text_field`               | –                                                                 |
| `number_integer`                | `min`, `max`                                                      |
| `number_decimal`                | `min`, `max`, `max_precision`                                     |
| `boolean`                       | –                                                                 |
| `color`                         | –                                                                 |
| `date`, `date_time`             | `min`, `max` (ISO strings)                                        |
| `weight`, `dimension`, `volume` | –                                                                 |
| `money`                         | –                                                                 |
| `rating`                        | – (constrained by `scale_min` / `scale_max` in the value itself)  |
| `url`                           | `allowed_schemes` (defaults to `["https","http","mailto","tel"]`) |
| `json`                          | –                                                                 |
| `*_reference`                   | –                                                                 |
| `list.<innerType>`              | `list_min`, `list_max` + inner-type validations applied per item  |

## Endpoints

| Method   | Route                        | Description                                                     |
| -------- | ---------------------------- | --------------------------------------------------------------- |
| `GET`    | `/metafield-definitions`     | [List with filters](/api-reference/metafields/definitions/list) |
| `POST`   | `/metafield-definitions`     | [Create](/api-reference/metafields/definitions/create)          |
| `GET`    | `/metafield-definitions/:id` | [Get one](/api-reference/metafields/definitions/get)            |
| `PUT`    | `/metafield-definitions/:id` | [Update](/api-reference/metafields/definitions/update)          |
| `DELETE` | `/metafield-definitions/:id` | [Delete](/api-reference/metafields/definitions/delete)          |

## Auth

Merchant JWT (owner, or staff with admin/manager access). The
`storeId` is resolved from the token.

## Notes for app developers

* You can still write metafield **values** under your own namespace
  without creating a definition first. The platform won't enforce types
  unless you've defined them.
* If you want merchants to see and edit your fields in the admin, ask the
  merchant (or your install flow) to create matching definitions. The
  definition + value combination is what populates the admin UI.
* **Deleting a definition does not delete the values.** Values persist;
  they just lose the schema. Cleaning up values requires explicit
  `DELETE /metafields/:id` calls.