Add portable metaobject definitions and references to Shopify Toolkit schema dump #25

gianlukk994 · 2025-10-15T13:17:02Z

Description

This PR implements support for dumping Shopify Metaobject definitions and references in the schema files, enabling schema portability across different Shopify stores.

Key Enhancements

Metaobject Definitions Dump
- Adds fetch_metaobject_definitions() method in schema.rb to retrieve metaobject schemas.
- Includes create_metaobject_definition calls in the schema dump output.
- Orders metaobjects before metafields in the dump for clarity.
- Handles metaobject field definitions, access controls, and capabilities.
Portable References
- Converts store-specific metaobject definition IDs (metaobject_definition_id) to portable metaobject types (metaobject_definition_type) in schema dumps.
- Updates validations to use types instead of GIDs via convert_validations_gids_to_types() method.
- Enhances metafield creation and update logic to resolve types back to GIDs when needed via convert_validations_types_to_gids().
- Supports both single and array values for list.metaobject_reference fields.
- Adds precise validation matching for metaobject reference fields.
Additional Features
- Created MetaobjectUtilities module to share common methods between modules.
- Enhanced schema loading to execute metaobject definitions before metafield definitions.
- Added deferred field validation system for handling dependencies between metaobjects.
Schema Structure Updates
- Updated schema header comment to mention both metafields and metaobjects.
- Added proper separation between metaobject and metafield definitions in dumps.
- Enhanced schema loading to process definitions in the correct order.

Example Before

create_metafield :products, :color, :metaobject_reference,
  validations: [{name: "metaobject_definition_id", value: "gid://shopify/MetaobjectDefinition/123"}]

Example After

create_metafield :products, :color, :metaobject_reference,
  validations: [{name: "metaobject_definition_type", value: "color_pattern"}]

With this update, schema files can be shared between stores without manual ID changes, as long as the relevant metaobject types exist.

Copilot

Pull Request Overview

Adds support for including metaobject definitions and portable metaobject reference validations in the schema dump to enable cross-store portability.

Introduces dumping of metaobject definitions before metafields.
Converts metaobject definition GID-based validations to portable type-based validations in both dump and load paths.
Adds bidirectional conversion logic (GIDs <-> types) and associated tests for one direction.

Reviewed Changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.

File	Description
spec/shopify_toolkit/schema_spec.rb	Adds test fixtures and specs for dumping metaobject definitions and converting validations from GIDs to types.
lib/shopify_toolkit/schema.rb	Adds metaobject fetching, schema generation with metaobjects, validation conversion, and type detection helpers.
lib/shopify_toolkit/metaobject_statements.rb	Adds helper to resolve a metaobject type from a GID for reverse validation conversion.
lib/shopify_toolkit/metafield_statements.rb	Adds conversion from metaobject types back to GIDs when creating/updating metafields, plus duplicate type check logic.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

spec/shopify_toolkit/schema_spec.rb

lib/shopify_toolkit/metafield_statements.rb

lib/shopify_toolkit/schema.rb

lib/shopify_toolkit/metafield_statements.rb

elia

I think some of the copilot suggestions for extraction could make sense, but feel free to postpone them to the future

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

lib/shopify_toolkit/schema.rb

lib/shopify_toolkit/metaobject_utilities.rb

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

lib/shopify_toolkit/schema.rb

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

lib/shopify_toolkit/schema.rb

lib/shopify_toolkit/metaobject_utilities.rb

lib/shopify_toolkit/schema.rb

Copilot

Pull Request Overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

lib/shopify_toolkit/schema.rb

lib/shopify_toolkit/metaobject_utilities.rb

lib/shopify_toolkit/metaobject_statements.rb

lib/shopify_toolkit/migrator.rb

Convert metaobject definition IDs to types in schema dumps to make them portable across different Shopify stores. Store-specific GIDs are now replaced with metaobject types that can be resolved in any store. Changes: - Add get_metaobject_definition_type_by_gid() method to resolve GIDs to types - Update schema dump to convert metaobject_definition_id validations to metaobject_definition_type - Enhance create_metafield and update_metafield to resolve types back to GIDs - Add precise validation matching for metaobject reference fields only - Support both single and array values for list.metaobject_reference fields - Include MetaobjectStatements in Schema module for type resolution Before: create_metafield :products, :color, :metaobject_reference, validations: [{name: "metaobject_definition_id", value: "gid://shopify/MetaobjectDefinition/123"}] After: create_metafield :products, :color, :metaobject_reference, validations: [{name: "metaobject_definition_type", value: "color_pattern"}] This enables schema files to be shared between different Shopify stores without manual ID updates, as long as the metaobject types exist.

Add support for dumping metaobject definitions in schema files with portable cross-store references. Metaobjects are now included before metafields in the schema dump output. Changes: - Add fetch_metaobject_definitions() method to retrieve metaobject schema - Include create_metaobject_definition calls in schema dump output - Convert metaobject references within metaobject fields to portable types - Update schema dump header to mention metaobjects - Order metaobjects before metafields in dump output - Handle metaobject field definitions, access controls, and capabilities - Skip default values (required: false, empty descriptions) for cleaner output Schema now generates: create_metaobject_definition :color_pattern, name: "Color Pattern", field_definitions: [{key: :name, type: :single_line_text_field, ...}], access: {admin: true, storefront: false} create_metafield :products, :color, :metaobject_reference, validations: [{name: "metaobject_definition_type", value: "color_pattern"}] This completes the portable schema dump feature by including both metaobjects and metafields with cross-store compatible references.

Separates the parsing of metaobjects and metafields schema definition

Extracts frequently used methods for handling metaobjects into a shared module.

Updates the metaobject creation logic to correctly handle and process metaobject reference fields

Updates the schema dump functionality to accept and process multiple metaobject_definition_ids

Enhances error handling for metafield creation failures.

Updates schema execution to defer field validation for cross-referencing metaobjects, preventing creation failure when a reference field points to a definition not yet created. The metaobject is created, and the validation update is deferred. Also, access management is updated to skip Admin access settings, as they are not settable via the GraphQL API, preserving only storefront access.

elia

Awesome to see this come along, all the comments can be handled in a different PR later on.

elia · 2025-10-31T10:20:01Z

lib/shopify_toolkit/schema.rb

+  def execute_metaobject_definitions(schema_content)
+    # Create a filtered version that only includes metaobject definitions
+    metaobject_content = filter_schema_content(schema_content, :metaobject)
+    eval_schema_content(metaobject_content)
+  end
+
+  def execute_metafield_definitions(schema_content)
+    # Create a filtered version that only includes metafield definitions
+    metafield_content = filter_schema_content(schema_content, :metafield)
+    eval_schema_content(metafield_content)
+  end
+
+  def filter_schema_content(schema_content, type)
+    lines = schema_content.lines
+    filtered_lines = []
+
+    # Always include the header and footer
+    filtered_lines << lines.first(8) # Header lines up to "ShopifyToolkit::Schema.define do"
+    filtered_lines.flatten!
+
+    lines.each do |line|
+      case type
+      when :metaobject
+        if line.strip.start_with?("create_metaobject_definition")
+          filtered_lines << line
+        end
+      when :metafield
+        filtered_lines << line if line.strip.start_with?("create_metafield")
+      end
+    end
+
+    filtered_lines << "end\n" # Closing line
+    filtered_lines.join
+  end
+
+  def eval_schema_content(content)
+    instance_eval(content)
+  end


I'm not to fond of this eval dance, but we can roll with it for now and improve later, my alternative idea would be to enforce the schema definition to declare things in the right order and keep using load here.

In other words if a metaobject definition comes after a metafield definition we throw an error and call it a day. We expect the schema to be generated anyway so it's acceptable to just bail out.

elia · 2025-10-31T10:22:57Z

lib/shopify_toolkit/schema.rb

+    say_with_time "Executing metafield definitions" do
+      # Execute only metafield definitions after all metaobjects exist
+      execute_metafield_definitions(schema_content)
    end


nit: you don't really "execute" a definition, would sound better as Loading ... definitions

gianlukk994 changed the title ~~Gianlukk994/support metaobjects schema dump~~ Add portable metaobject definitions and references to Shopify Toolkit schema dump Oct 15, 2025

gianlukk994 marked this pull request as ready for review October 15, 2025 13:42

gianlukk994 requested review from Copilot and elia October 15, 2025 13:42

Copilot AI reviewed Oct 15, 2025

View reviewed changes

elia approved these changes Oct 16, 2025

View reviewed changes

gianlukk994 requested a review from Copilot October 22, 2025 15:11

Copilot AI reviewed Oct 22, 2025

View reviewed changes

lib/shopify_toolkit/schema.rb Outdated Show resolved Hide resolved

lib/shopify_toolkit/metaobject_utilities.rb Outdated Show resolved Hide resolved

gianlukk994 force-pushed the gianlukk994/support-metaobjects-schema-dump branch from 3eb2ee9 to 5bfb288 Compare October 23, 2025 11:39

gianlukk994 requested a review from Copilot October 23, 2025 11:39

Copilot AI reviewed Oct 23, 2025

View reviewed changes

gianlukk994 force-pushed the gianlukk994/support-metaobjects-schema-dump branch from 5bfb288 to 3aede8b Compare October 23, 2025 12:00

gianlukk994 requested a review from Copilot October 23, 2025 12:01

Copilot AI reviewed Oct 23, 2025

View reviewed changes

gianlukk994 self-assigned this Oct 27, 2025

gianlukk994 requested a review from Copilot October 30, 2025 17:03

Copilot AI reviewed Oct 30, 2025

View reviewed changes

gianlukk994 force-pushed the gianlukk994/support-metaobjects-schema-dump branch from 70443b7 to 84f2d9b Compare October 30, 2025 17:26

gianlukk994 requested a review from elia October 30, 2025 17:30

gianlukk994 added 9 commits October 30, 2025 18:35

Separate metaobjects and metafields schema parse

0f2c205

Separates the parsing of metaobjects and metafields schema definition

Extract common metaobject methods to shared module

505237f

Extracts frequently used methods for handling metaobjects into a shared module.

Handle metaobject reference fields on creation

9cd61f9

Updates the metaobject creation logic to correctly handle and process metaobject reference fields

Enhance schema dump with multiple metaobject IDs

46c1ddc

Updates the schema dump functionality to accept and process multiple metaobject_definition_ids

Add metaobject statements to migrator

979ebb0

Handle failed metafield creation with context

ddab845

Enhances error handling for metafield creation failures.

gianlukk994 force-pushed the gianlukk994/support-metaobjects-schema-dump branch from 84f2d9b to 7d34277 Compare October 30, 2025 17:36

elia approved these changes Oct 31, 2025

View reviewed changes

Update README

25a2276

gianlukk994 merged commit a80474c into main Oct 31, 2025
3 checks passed

gianlukk994 deleted the gianlukk994/support-metaobjects-schema-dump branch October 31, 2025 11:23

Add portable metaobject definitions and references to Shopify Toolkit schema dump #25

Add portable metaobject definitions and references to Shopify Toolkit schema dump #25

Uh oh!

Conversation

gianlukk994 commented Oct 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Key Enhancements

Example Before

Example After

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elia left a comment

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

elia left a comment

Choose a reason for hiding this comment

Uh oh!

elia Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

elia Oct 31, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

gianlukk994 commented Oct 15, 2025 •

edited

Loading