# Metafield definitions

> A Metafield definition declares a custom field on an owner type, with a key, data type and validations.

A **Metafield definition** declares a **custom field** you can attach to a resource. It sets the field's `namespace` and `key` (which together identify it), the `ownerType` it applies to (such as `product`), the `type` of data it holds, and any `validations` and `constraints` that values must satisfy.

Definitions are the **schema**; the actual values are [Metafields](/api/product-management/metafields/) stored on individual owner records. Define a field once, then set its value on each product, variant, and so on.

## The Metafield definition object

## Common workflows

- **Add a custom field.** Create a definition with a `namespace`, `key`, `ownerType` and `type`, then set [Metafield](/api/product-management/metafields/) values on records of that owner type.
- **Constrain values.** Attach `validations` (for example a maximum length or a numeric range) so invalid values are rejected when a metafield is written.
- **Audit usage.** Each definition reports a `metafieldsCount` - how many records currently carry a value for it.

## Type compatibility

Which `validations` and `constraints` you can attach is **not free-form** - it depends on the definition's type, and the API rejects an incompatible combination with `422 Unprocessable Entity`. The rules differ for the two:

- **Validations depend on the `type`.** A `number_decimal` accepts numeric validations (`min_value`, `max_value`, `max_precision`); a text type accepts `min_length` / `max_length`; a `json` type accepts `json_schema`; reference types accept none. The authoritative, always-current list for each type is the **`allowedValidations`** field on [Metafield definition types](/api/product-management/metafield-definition-types/) - query that resource rather than hard-coding a table.
- **Constraints depend on the `ownerType`, not the type.** Constraints (`category`, `channel`, `category_channel`) are scoped to the owner resource. **Today only `products` allows constraints**; every other owner type allows none. The authoritative list is the **`allowedConstraints`** field on [Metafield owner types](/api/product-management/metafield-owner-types/).

> [!TIP]
> Before creating a definition, read the matching [definition type](/api/product-management/metafield-definition-types/) and [owner type](/api/product-management/metafield-owner-types/) to see exactly what it accepts. That way your `validations` and `constraints` are valid by construction.

Submitting an incompatible rule returns `422` with a message such as `Validation "min_value" is not compatible with metafield definition type "single_line_text_field".` or `Constraint "category" is not compatible with owner type "variants".`

## Conventions

### Authentication and headers

All requests require an OAuth 2.0 bearer token and the organization scope header:

```
Authorization: Bearer <token>
X-Flowkiwi-Organization-Id: <organization-id>
```

### Partial updates

`PATCH` uses [JSON Merge Patch](https://datatracker.ietf.org/doc/html/rfc7396) with `Content-Type: application/merge-patch+json`.