# Metaobject definitions

> A Metaobject definition declares a reusable custom object type with its own fields.

A **Metaobject definition** declares a **brand-new object type** of your own - something that doesn't exist as a built-in resource. Where a [Metafield definition](/api/product-management/metafield-definitions/) adds **one field** to an existing record (a product, a variant), a metaobject definition describes a **whole structured record**: a set of `fieldDefinitions`, each with its own `key`, `type` and `validations`.

Think of it as defining a content type. A "Size guide", an "Author", an "Ingredient" - none of these are products, but you may want to model them once and reuse them. The definition is the **blueprint**; the actual records are [Metaobjects](/api/product-management/metaobjects/) built from it.

Each definition has a `type` (a unique slug such as `size_guide`), a `name`, an optional `displayNameField` (which field to show as a record's label), and its `fieldDefinitions`.

## The Metaobject definition object

## How it fits together

1. **Define** the type here - its `type` slug and `fieldDefinitions`.
2. **Create** [Metaobjects](/api/product-management/metaobjects/) of that type - one record per entry, each with a `handle` and field values.
3. **Reference** those records from a product or variant through a [Metafield](/api/product-management/metafields/) whose definition `type` is a metaobject reference.

## Common workflows

- **Model a content type.** Create a definition with the `fieldDefinitions` your records need, then add metaobjects for it.
- **Pick a label.** Set `displayNameField` to the field key that best identifies a record (for example a `title` field).
- **Evolve it.** [Patch](/api/product-management/metaobject-definitions/update/) the definition to add or adjust `fieldDefinitions` as your model grows.

## 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`.