# Metafields and metadata

Metafields add typed, named data to supported Thor resources.
Metadata stores string key-value pairs on a resource.
Choose between them based on who reads the value and what validation it needs.

## Choose the right place

| Data | Recommended place |
| --- | --- |
| Variant price or stock | Native price or inventory records |
| Product color used to select a variant | Attribute and variant selection |
| Translated product description | Translations |
| Lamp wattage displayed and filtered by buyers | Integer metafield |
| External catalog row identifier | Namespaced metadata or your integration mapping |

Do not use custom data to bypass the price, inventory, or customer model.
Thor's native calculations do not derive their inputs from arbitrary metadata.

## Definition and value

A metafield definition gives a namespace, key, owner type, kind, and validation settings.
Create the definition first.
Assign a value through the owner's create or update input, such as `ProductUpdateInput.metafields`.
Definition mutations manage the field contract; owner mutations manage values.

Choose names such as `specs.wattage` that will remain meaningful after a UI redesign.
Treat a change of kind or owner as a consumer-facing contract change.

## Visibility is a deliberate choice

Set `isPrivate` explicitly on a new definition.
Only make a field public when its value is intended for the owner's Storefront surface.
Verify it through that API before building a dependency on it.
Metadata is not a secret store: a string collection does not provide a blanket confidentiality guarantee.
Keep credentials, internal costs, and sensitive operational notes out of public custom data.

Follow [Add custom data](/guides/catalog/custom-data) for a complete definition, value, and read example.