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() 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.
- Skips default values for cleaner output.
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, making schema files cross-store compatible.
- Enhances metafield creation and update logic to resolve types back to GIDs when needed.
- Supports both single and array values for list.metaobject_reference fields.
- Adds precise validation matching for metaobject reference fields.

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.

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.

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.}

Copilot · 2025-10-15T13:45:15Z

spec/shopify_toolkit/schema_spec.rb

+      expected_schema =
+        (
+          if RUBY_VERSION.to_f < 3.4
+            SCHEMA_FIXTURE_BEFORE_RUBY_3_4
+          else
+            SCHEMA_FIXTURE
+          end
+        )


Version comparison using RUBY_VERSION.to_f is unsafe for multi-digit minor versions (e.g. '3.10' becomes 3.1). Use Gem::Version: if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('3.4') instead.

Copilot · 2025-10-15T13:45:16Z

lib/shopify_toolkit/metafield_statements.rb

+    # Process validations to convert metaobject types to GIDs (only for metaobject reference fields)
+    if options[:validations] && is_metaobject_reference_type?(type)
+      options[:validations] = convert_validations_types_to_gids(options[:validations])
+    end
+
    # Skip creation if metafield already exists
    if get_metafield_gid(owner_type, key, namespace: namespace)


Validation conversion occurs before the existence check; if the metafield already exists and a referenced metaobject type is missing, this can raise unnecessarily. Move the conversion logic after the early-return existence check.

Copilot · 2025-10-15T13:45:16Z

lib/shopify_toolkit/metafield_statements.rb

+    # Process validations to convert metaobject types to GIDs (only for metaobject reference fields)
+    if options[:validations] && options[:type] && is_metaobject_reference_type?(options[:type])
+      options[:validations] = convert_validations_types_to_gids(options[:validations])
+    end
+
    unless get_metafield_gid(owner_type, key, namespace: namespace)
      say "Metafield #{namespace}:#{key} not found for #{owner_type}, skipping update"


Validation conversion (which can raise on missing types) is performed before confirming the metafield exists. Move the conversion inside the branch after the existence check to avoid unnecessary errors when skipping.

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

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

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.}

Copilot · 2025-10-23T12:02:12Z

lib/shopify_toolkit/schema.rb

+  def convert_validations_gids_to_types(validations, metafield_type)
+    return validations unless validations&.any? && is_metaobject_reference_type?(metafield_type)
+
+    validations.filter_map do |validation|
+      convert_metaobject_validation_to_type(validation)
+    end
+  end
+
+  private


[nitpick] The convert_validations_gids_to_types method is marked as public but convert_metaobject_validation_to_type and related helper methods are private. This creates an inconsistent API where public methods depend on private implementation details. Consider making this method private as well since it appears to be an internal helper called by generate_schema_content.

Copilot · 2025-10-23T12:02:12Z

lib/shopify_toolkit/schema.rb

+    type = get_metaobject_definition_type_by_gid(gid)
+
+    if type.nil?
+      puts "Warning: Metafield validation references unknown metaobject GID #{gid} - excluding from portable schema"


Direct use of puts bypasses the Rails logger. Use logger.warn instead for consistency with the rest of the codebase and proper log level handling.

Suggested change

puts "Warning: Metafield validation references unknown metaobject GID #{gid} - excluding from portable schema"

logger.warn "Metafield validation references unknown metaobject GID #{gid} - excluding from portable schema"

Copilot · 2025-10-23T12:02:12Z

lib/shopify_toolkit/metaobject_utilities.rb

+            "# GraphQL
+              query GetMetaobjectDefinitionID($type: String!) {
+                metaobjectDefinitionByType(type: $type) {
+                  id
+                }
+              }",


The comment # GraphQL should be inside the string as part of the GraphQL query, not a Ruby comment. Change to \"query GetMetaobjectDefinitionID($type: String!) { without the # GraphQL prefix.

Copilot · 2025-10-23T12:02:13Z

lib/shopify_toolkit/metaobject_utilities.rb

+            "# GraphQL
+              query GetMetaobjectDefinitionType($id: ID!) {
+                metaobjectDefinition(id: $id) {
+                  type
+                }
+              }",


The comment # GraphQL should be inside the string as part of the GraphQL query, not a Ruby comment. Change to \"query GetMetaobjectDefinitionType($id: ID!) { without the # GraphQL prefix.

lib/shopify_toolkit/schema.rb

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 added 6 commits October 23, 2025 13:59

Separate metaobjects and metafields schema parse

b019dfd

Separates the parsing of metaobjects and metafields schema definition

Extract common metaobject methods to shared module

1a9a60d

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

Handle metaobject reference fields on creation

ac6320f

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

Enhance schema dump with multiple metaobject IDs

a67db25

Updates the schema dump functionality to accept and process multiple metaobject_definition_ids

Add metaobject statements to migrator

3aede8b

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

	puts "Warning: Metafield validation references unknown metaobject GID #{gid} - excluding from portable schema"
	logger.warn "Metafield validation references unknown metaobject GID #{gid} - excluding from portable schema"

Uh oh!

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

Are you sure you want to change the base?

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

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!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 15, 2025

Choose a reason for hiding this comment

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!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

gianlukk994 commented Oct 15, 2025 •

edited

Loading