Skip to main content

Metaobject Definition Fields

Templates that define the structure and behavior of metaobjects in Shopify

Updated this week

Sample File

This sample file shows the basic columns that you need to set in order to import metaobject definitions to Shopify.

Notes

Shopify-Managed Definitions

By default, Altera will not export Shopify-managed metaobject definitions during exports.

Shopify manages certain metaobject definitions internally (typically with type names starting with shopify--, such as shopify--color-pattern). These are used for Shopify Product Taxonomy and are system-managed definitions that cannot be created, updated, or modified through the API.

Why they're excluded by default:

  • Shopify-managed definitions cannot be imported back into stores as the API does not allow it

  • Attempting to import them will result in errors (MOBD001)

If you need to export them anyway: You can include Shopify-managed definitions in your export by removing the "Is managed by Shopify" filter when configuring your export. This might be useful for documentation or analysis purposes, but remember that these definitions cannot be imported back into any store.

What you can import: Only custom metaobject definitions (those not managed by Shopify) can be successfully imported through Altera.

General

ID

Description

Example Value

Unique definition identifier

gid://shopify/MetaobjectDefinition/6304792762

If present, the ID will be used to find an existing metaobject definition on the store. When importing, the ID will be used to see if the definition already exists. If there's no ID match the app will attempt to find an existing definition using the Type.

Type

Description

Example Value

The metaobject type identifier (Create-only)

celebrity

The unique type identifier for this metaobject definition. This is used to identify the type of metaobjects created from this definition. This field can only be set during creation and cannot be changed later.

Command

Description

Example Value

Action to perform: MERGE, DELETE, NEW

MERGE

  • MERGE: Update existing definition or create if not found

  • DELETE: Remove the definition from the store (only if no metaobjects reference it)

  • NEW: Create a new definition (will fail if definition already exists)

Name

Description

Example Value

Display name for the metaobject definition

Celebrity

The human-readable name for this metaobject definition that appears in the Shopify admin.

Description

Description

Example Value

Description of the metaobject definition

my description

A description explaining what this metaobject definition is used for.

Metaobject Count

Description

Example Value

Number of metaobjects using this definition (Export-only)

3

The total number of metaobjects that have been created using this definition. This field is export-only and cannot be imported.

Access: Storefront API

Description

Example Value

Storefront API access level

PUBLIC_READ

Controls how the metaobjects can be accessed via the Storefront API:

  • PUBLIC_READ: Publicly readable via Storefront API

  • PRIVATE: Private access only, not available via Storefront API

Access: Admin API

Description

Example Value

Admin API access level

PUBLIC_READ_WRITE

Controls how the metaobjects can be accessed via the Admin API:

  • MERCHANT_READ: Merchant read access only

  • MERCHANT_READ_WRITE: Merchant read and write access

  • PUBLIC_READ_WRITE: Public read and write access

Capability: Active-draft status

Description

Example Value

Whether metaobjects can have active/draft status

TRUE

  • TRUE: Metaobjects can be saved as drafts or published as active

  • FALSE: Metaobjects are always active when created

Capability: Translations

Description

Example Value

Whether metaobjects support translations

TRUE

  • TRUE: Metaobjects can be translated into multiple languages

  • FALSE: Metaobjects do not support translations

Capability: Publish entries as web pages

Description

Example Value

Whether metaobjects can be published as web pages

FALSE

  • TRUE: Metaobjects can be published as standalone web pages with URLs

  • FALSE: Metaobjects cannot be published as web pages

Capability: Storefronts API access

Description

Example Value

Whether metaobjects are accessible via Storefronts API

FALSE

  • TRUE: Metaobjects are accessible via the Storefronts API

  • FALSE: Metaobjects are not accessible via the Storefronts API

Row

Description

Example Value

Row number for multi-row data

1

Used when a metaobject definition spans multiple rows (e.g., when including multiple field definitions).

Top Row

Description

Example Value

Whether this is the first row for this definition

TRUE

  • TRUE: This is the primary row for the definition

  • FALSE: This is a secondary row for additional field or validation data

Field Definitions

Field: Key

Description

Example Value

Unique identifier for the field within the definition (Create-only)

name

The unique key for this field within the metaobject definition. This can only be set during creation and cannot be changed later.

Field: Description

Description

Example Value

Description of what this field stores

my description

A description explaining what this field is used for.

Field: Type

Description

Example Value

Data type of the field (Create-only)

single_line_text_field

The type of data this field can store. Common field types include:

  • single_line_text_field: Single line text input

  • multi_line_text_field: Multi-line text input

  • number_integer: Integer number

  • number_decimal: Decimal number

  • date: Date field

  • date_time: Date and time field

  • boolean: True/false field

  • color: Color picker

  • file_reference: File reference

  • url: URL field

  • json: JSON data

  • rating: Rating field

  • dimension: Dimension field

  • volume: Volume field

  • weight: Weight field

  • money: Money field

  • product_reference: Product reference

  • variant_reference: Variant reference

  • page_reference: Page reference

  • collection_reference: Collection reference

  • mixed_reference: Mixed reference

This field can only be set during creation and cannot be changed later.

Field: Required

Description

Example Value

Whether this field is required when creating metaobjects

FALSE

  • TRUE: This field must be provided when creating metaobjects

  • FALSE: This field is optional

Field: Display Name

Description

Example Value

Whether this field is used as the display name for metaobjects

TRUE

  • TRUE: The value of this field will be used as the display name for metaobjects

  • FALSE: This field is not used for the display name

Validations

Validation: Name

Description

Example Value

Name of the validation rule

min

The name of the validation rule being applied to a field. Common validation rules include:

  • min: Minimum value (for numbers) or length (for text)

  • max: Maximum value (for numbers) or length (for text)

  • regex: Regular expression pattern

  • file_type_options: Allowed file types (for file references)

  • choices: Predefined choices for the field

Validation: Type

Description

Example Value

Data type of the validation (Export-only)

number_integer

The data type of the validation value. This field is export-only and cannot be imported.

Validation: Value

Description

Example Value

Value used for the validation

1

The value that defines the validation rule. For example, if the validation name is "min", this would be the minimum value or length allowed.

Export Filters

You can use these filters to limit which metaobject definitions are exported:

  • type: Filter by definition type

  • updated_at: Filter by last update date

Did this answer your question?