Add schema definition extension plumbing

Author: jwils

config/site/support/doctest_helper.rb

@@ -82,7 +82,7 @@ module ElasticGraph
         artifacts_manager = @api.factory.new_schema_artifact_manager(
           schema_definition_results: @api.results,
           schema_artifacts_directory: "#{@tmp_dir}/schema_artifacts",
-          enforce_json_schema_version: true,
+          extension_artifact_options: {enforce_json_schema_version: true},
           output: ::StringIO.new
         )
 

elasticgraph-admin/spec/integration/elastic_graph/admin/index_definition_configurator/for_index_template_spec.rb

@@ -167,7 +167,7 @@ def fetch_artifact_configuration(schema_artifacts, index_def_name)
               factory.new_schema_artifact_manager(
                 schema_definition_results: schema_def_results,
                 schema_artifacts_directory: Dir.pwd,
-                enforce_json_schema_version: true,
+                extension_artifact_options: {enforce_json_schema_version: true},
                 output: output_io
               ).dump_artifacts
 

elasticgraph-apollo/apollo_tests_implementation/Rakefile

@@ -6,6 +6,7 @@
 #
 # frozen_string_literal: true
 
+require "elastic_graph/schema_definition/extension_module_support"
 require "elastic_graph/schema_definition/rake_tasks"
 require "elastic_graph/apollo/schema_definition/api_extension"
 require "pathname"
@@ -17,6 +18,7 @@ ElasticGraph::SchemaDefinition::RakeTasks.new(
   index_document_sizes: false,
   path_to_schema: project_root / "config/products_schema.rb",
   schema_artifacts_directory: project_root / "config/schema/artifacts",
-  extension_modules: [ElasticGraph::Apollo::SchemaDefinition::APIExtension],
-  enforce_json_schema_version: false
+  # Include the JSON ingestion default alongside the Apollo extension so the apollo tests dump JSON schemas.
+  extension_modules: ElasticGraph::SchemaDefinition::ExtensionModuleSupport.default_extension_modules + [ElasticGraph::Apollo::SchemaDefinition::APIExtension],
+  extension_artifact_options: {enforce_json_schema_version: false}
 )

elasticgraph-graphql/spec/acceptance/schema_evolution_spec.rb

@@ -68,7 +68,7 @@ def dump_schema_artifacts(json_schema_version:, team_extras: "")
           index_document_sizes: true,
           path_to_schema: path_to_schema,
           schema_artifacts_directory: "config/schema/artifacts",
-          enforce_json_schema_version: true,
+          extension_artifact_options: {enforce_json_schema_version: true},
           output: output
         )
       end

elasticgraph-indexer/spec/acceptance/schema_evolution_spec.rb

@@ -404,7 +404,7 @@ def dump_artifacts
           index_document_sizes: true,
           path_to_schema: path_to_schema,
           schema_artifacts_directory: "config/schema/artifacts",
-          enforce_json_schema_version: true,
+          extension_artifact_options: {enforce_json_schema_version: true},
           output: output
         )
       end

elasticgraph-local/lib/elastic_graph/local/rake_tasks.rb

@@ -361,7 +361,7 @@ def initialize(local_config_yaml:, path_to_schema:)
         self.derived_type_name_formats = {}
         self.type_name_overrides = {}
         self.enum_value_overrides_by_type = {}
-        self.schema_definition_extension_modules = []
+        self.schema_definition_extension_modules = SchemaDefinition::ExtensionModuleSupport.default_extension_modules
         self.enforce_json_schema_version = true
         self.env_port_mapping = {}
         self.output = $stdout
@@ -394,7 +394,7 @@ def initialize(local_config_yaml:, path_to_schema:)
           type_name_overrides: type_name_overrides,
           enum_value_overrides_by_type: enum_value_overrides_by_type,
           extension_modules: schema_definition_extension_modules,
-          enforce_json_schema_version: enforce_json_schema_version,
+          extension_artifact_options: {enforce_json_schema_version: enforce_json_schema_version},
           output: output
         )
 

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/api.rb

@@ -9,6 +9,7 @@
 require "elastic_graph/errors"
 require "elastic_graph/schema_artifacts/runtime_metadata/extension"
 require "elastic_graph/schema_artifacts/runtime_metadata/graphql_resolver"
+require "elastic_graph/schema_definition/extension_module_support"
 require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
 require "elastic_graph/schema_definition/results"
 require "elastic_graph/schema_definition/state"
@@ -59,7 +60,7 @@ class API
       def initialize(
         schema_elements,
         index_document_sizes,
-        extension_modules: [],
+        extension_modules: ExtensionModuleSupport.default_extension_modules,
         derived_type_name_formats: {},
         type_name_overrides: {},
         enum_value_overrides_by_type: {},
@@ -77,7 +78,7 @@ def initialize(
 
         @factory = @state.factory
 
-        extension_modules.each { |mod| extend(mod) }
+        extension_modules.uniq.each { |mod| extend(mod) }
 
         # These lines must come _after_ the extension modules are applied, so that the extension modules
         # have a chance to hook into the factory in order to customize built in types if desired.

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/extension_module_support.rb

@@ -0,0 +1,23 @@
+# Copyright 2024 - 2026 Block, Inc.
+#
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
+# frozen_string_literal: true
+
+module ElasticGraph
+  module SchemaDefinition
+    # Helper methods for composing schema definition extension modules.
+    #
+    # @private
+    module ExtensionModuleSupport
+      # Default extension modules applied to {API} when none are explicitly specified.
+      #
+      # @return [Array<Module>] default extension modules
+      def self.default_extension_modules
+        []
+      end
+    end
+  end
+end

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/factory.rb

@@ -59,6 +59,10 @@ module SchemaDefinition
     class Factory
       include Mixins::HasReadableToSAndInspect.new
 
+      # @dynamic state
+      # @return [State] schema definition state shared with the factory's API
+      attr_reader :state
+
       def initialize(state)
         @state = state
       end
@@ -297,15 +301,15 @@ def new_results
       def new_schema_artifact_manager(
         schema_definition_results:,
         schema_artifacts_directory:,
-        enforce_json_schema_version:,
         output:,
+        extension_artifact_options: {},
         max_diff_lines: 50
       )
         @@schema_artifact_manager_new.call(
           schema_definition_results:,
           schema_artifacts_directory:,
-          enforce_json_schema_version:,
           output:,
+          extension_artifact_options:,
           max_diff_lines:
         )
       end

elasticgraph-schema_definition/lib/elastic_graph/schema_definition/rake_tasks.rb

@@ -8,6 +8,7 @@
 
 require "rake/tasklib"
 require "elastic_graph/schema_artifacts/runtime_metadata/schema_element_names"
+require "elastic_graph/schema_definition/extension_module_support"
 
 module ElasticGraph
   module SchemaDefinition
@@ -41,12 +42,8 @@ class RakeTasks < ::Rake::TaskLib
       #   specific enum types. For example, to rename the `DayOfWeek.MONDAY` enum to `DayOfWeek.MON`, pass `{DayOfWeek: {MONDAY: "MON"}}`.
       # @param extension_modules [Array<Module>] List of Ruby modules to extend onto the `SchemaDefinition::API` instance. Designed to
       #   support ElasticGraph extension gems (such as `elasticgraph-apollo`).
-      # @param enforce_json_schema_version [Boolean] Whether or not to enforce the requirement that the JSON schema version is incremented
-      #   every time dumping the JSON schemas results in a changed artifact. Generally speaking, you will want this to be `true` for any
-      #   ElasticGraph application that is in production as the versioning of JSON schemas is what supports safe schema evolution as it
-      #   allows ElasticGraph to identify which version of the JSON schema the publishing system was operating on when it published an
-      #   event. It can be useful to set it to `false` before your application is in production, as you do not want to be forced to bump
-      #   the version after every single schema change while you are building an initial prototype.
+      # @param extension_artifact_options [Hash<Symbol, Object>] Hash of options forwarded to extension-defined schema artifacts. The JSON
+      #   schema artifact dumper reads `:enforce_json_schema_version` from this hash; extension gems can read their own keys.
       # @param output [IO] used for printing task output
       #
       # @example Minimal setup with defaults
@@ -116,8 +113,8 @@ def initialize(
         derived_type_name_formats: {},
         type_name_overrides: {},
         enum_value_overrides_by_type: {},
-        extension_modules: [],
-        enforce_json_schema_version: true,
+        extension_modules: ExtensionModuleSupport.default_extension_modules,
+        extension_artifact_options: {},
         output: $stdout
       )
         @schema_element_names = SchemaArtifacts::RuntimeMetadata::SchemaElementNames.new(
@@ -131,7 +128,7 @@ def initialize(
         @index_document_sizes = index_document_sizes
         @path_to_schema = path_to_schema
         @schema_artifacts_directory = schema_artifacts_directory
-        @enforce_json_schema_version = enforce_json_schema_version
+        @extension_artifact_options = extension_artifact_options
         @extension_modules = extension_modules
         @output = output
 
@@ -164,7 +161,7 @@ def schema_artifact_manager
         schema_def_api.factory.new_schema_artifact_manager(
           schema_definition_results: schema_def_api.results,
           schema_artifacts_directory: @schema_artifacts_directory.to_s,
-          enforce_json_schema_version: @enforce_json_schema_version,
+          extension_artifact_options: @extension_artifact_options,
           output: @output,
           max_diff_lines: max_diff_lines
         )