4 min read

Content types (metaobjects)

Merchants see Content types, Entries and Extra fields. The code, the API (metaobjects.*), templates and these docs keep Shopify’s names: a metaobject definition (metaobject_definition) with entries (metaobject), and metafields (metafield_definition, metafield) on products, variants, collections, customers, orders, pages, articles and the shop. Merchant guide: Content types.

Everything in schemas.ts, validate.ts, field-values.ts and presets.ts is browser-safe (@commerce/core/metaobjects): the admin runs the same checks for inline errors, and the server runs them again before anything is written.

Field types and stored values

The type is plain text in the database (no CHECK), so adding a type needs no migration. FIELD_TYPES (core) and METAFIELD_TYPES (@commerce/db) must stay equal; a test checks it.

Lists (list: true) store an array of the single value. boolean, rich_text, multi_line_text and group cannot be lists.

Groups (rows of fields)

A group is a list of rows, one level deep, after Payload CMS’s array field and Instatic’s repeater (both MIT; ideas only, see THIRD_PARTY_NOTICES.md). Its validations.subfields are GroupFields: { key, name, type, required, validations }, where type is one of GROUP_FIELD_TYPES (plain values and file; no references to other records, no nested groups). Each row is checked against them: keys a row field does not know are dropped, blank rows are left out, and errors name the row (Sizes row 2: Size is required). Files picked in rows are checked to exist like any other reference and resolve to { id, url, alt } on the storefront.

The field-change lock

Saved values were checked against the field as it was, so a field’s kind of value cannot change while any entry holds a value in it. updateDefinition calls storedFieldProblems (field-changes.ts), which counts values per key (filledFieldKeys, one jsonb_object_keys query) and refuses:

• a different type or list flag,
• a different currency (money) or measure (measurement),
• a group row field kept under the same key with a different type, currency or unit kind.

Renaming, rules such as choices or ratingMax, required, and adding or removing row fields are fine. A field removed earlier keeps its old values in the rows; adding a field back under that key is allowed only when every old value fits the new field. The message is plain words: Fit already has values in 3 entries, so what goes in it cannot change. Add a new field instead, or clear it in those entries first. metaobjects.definition returns filled (per-key counts) so the admin greys out What goes in it with that reason. Metafield definitions never change type after creation.

References

referenceProblems (references.ts) confirms every id under RLS, so another store’s id reads as deleted. metaobjects.references serves the pickers: kind is one of product, variant (named Product · Variant, searchable by SKU), collection, page, article (detail: its blog), metaobject and file.

On the storefront (storefront.ts) references resolve one level deep and hidden targets drop out: products and collections that are not active, pages without published_at, blog posts not yet visible (visibleNow), archived variants or variants of inactive products, and hidden or draft entries.

Metafield owners and permissions

METAFIELD_OWNER_TYPES (schemas.ts) lists the owners: product, variant, collection, customer, order, page, article and shop. Migration 0108_metafield_owners widened the metafield_definition_owner CHECK to match (MetafieldOwnerType in @commerce/db is the same union). shop values hang on the store row itself: the API ignores any ownerId and uses the caller’s store id; every other owner needs ownerId, and setMetafields checks the row exists in the store (RLS hides other stores’ rows, the store row included).

• Values are guarded by the record’s own access, METAFIELD_OWNER_PERMISSIONS (owner-permissions.ts): products, variants and collections products.*, customers customers.*, orders orders.*, pages online_store.*, articles content.*, the shop settings.read / settings.manage. The procedures use canAny and then check the exact grain (assertOwnerAccess); listing definitions is also allowed with content.manage_types.
• Definitions (metafield definitions and content types) need content.manage_types. 0108 grants it to every role that held content.write or settings.manage (the old guards) and to the system Administrator role.
• PRIVATE_METAFIELD_OWNERS (customer, order) always save storefront_access = false; the storefront only ever reads product and collection metafields.
• deleteMetafieldsOf removes a customer’s values when the customer is deleted (deleteCustomer) or erased (anonymiseCustomer).
• Admin: MetafieldsCard takes any owner (the shop with ownerId={null}), hides Save without the write grain and “Add a field” without content.manage_types; VariantMetafieldsCard adds a variant picker on the product page; Settings → Custom data has a tab per owner.

Theme bindings

Settings connect to metaobjects.<type>.<handle>.<key> and product|collection.metafields.<namespace>.<key> exactly as before; the new types just fit more settings. See Dynamic sources.

Importing from Shopify

The value shapes follow Shopify’s metafield types so an importer can map them field by field: color → color; date_time → date_time; money { amount: "5.99", currency_code } → money { amount: 599, currency }; link { text, url } → link { label, url }; rating { value, scale_max } → rating { value, max }; weight / dimension / volume { value, unit } → measurement with measure weight / length / volume (units outside our list need converting); page_reference, variant_reference → the same; an article reference → article_reference; a list.single_line_text_field with choices → a choice list. Groups have no Shopify metafield equivalent (Shopify uses a list of metaobject references).