Docs › What you can import › Metaobject definitions

Metaobject definitions

One row creates one metaobject definition, with all of its fields. A metaobject is a custom content type of your own — an Author, a Size chart, a Store location, an FAQ — that isn't a product, page or collection.

A worked example

type,name,fields,displayNameKey,publishable,storefrontAccess
author,Author,name*:single_line_text_field|bio:multi_line_text_field|photo:file_reference,name,true,PUBLIC_READ
ingredient,Ingredient,name*:single_line_text_field|allergen:boolean,name,false,PUBLIC_READ

Two definitions, two credits. The first creates an author type with three fields, where name is required and doubles as the display name, and entries can be draft or published.

The fields column

This is the only genuinely unusual thing about this import type. A CSV row can't have a variable number of columns, and a definition can have any number of fields — so the whole field set is packed into a single cell.

Compact form

key:type pairs separated by |. A trailing * on the key marks the field required. :required works too.

name*:single_line_text_field|bio:multi_line_text_field|photo:file_reference

That cell means:

No commas are involved, so the cell doesn't need quoting — which is exactly why the pipe was chosen as the separator.

JSON form

For anything more elaborate, or if you're generating the file from a script, a JSON array is accepted. Remember to quote the cell, because it contains commas.

[{"key":"name","type":"single_line_text_field","required":true},
 {"key":"bio","type":"multi_line_text_field"}]

Field types are the same catalogue metafields use — see metafield types. Reference types are allowed, so a metaobject can point at products, files or other metaobjects.

Columns

Required

Optional

Capabilities, briefly

publishable

Entries get a draft/published status, so you can load content before it goes live. Turn it on and the entries importer gains a status column accepting ACTIVE or DRAFT.

onlineStoreUrlHandle

Makes entries addressable on your storefront under /pages/<handle>. Set it to a plural noun — authors, locations.

renderableMetaTitleKey / renderableMetaDescriptionKey

Enables the renderable capability, letting Shopify build SEO tags for those pages from fields you nominate.

translatable

Makes entry content available to Shopify's translation tooling.

Rules enforced before anything reaches Shopify

• Type — 3–255 characters, letters, numbers, hyphens, underscores, and immutable once created.
• An $app: prefix is stripped with a warning, and the definition is imported as merchant-owned. App-reserved types belong to apps, and a CSV import creates definitions you own.
• displayNameKey must be one of the keys in fields.
• Duplicate rows — two rows with the same type: the second is flagged duplicate of row N.
• Field types are immutable. This shapes update behaviour — see below.

Re-importing a definition that exists

A definition is identified by its type. Your conflict mode decides what happens:

A practical consequence: adding a field to an existing definition works well. Re-import the row with the extra field in the fields cell, in Update mode, and only the new field is created.

After importing definitions

Check them in the Shopify admin at Settings → Custom data → Metaobjects, then:

• Import the entries. The target selector on the upload step will list your new definition, and the columns will be its fields.
• Import metafield definitions that reference it, using the metaobject_reference<author> shorthand — now that the definition exists, the reference resolves cleanly.