Add schema definition extension plumbing

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
         )

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

@@ -31,10 +31,10 @@ class SchemaArtifactManager
       # @dynamic schema_definition_results
       attr_reader :schema_definition_results
 
-      def initialize(schema_definition_results:, schema_artifacts_directory:, enforce_json_schema_version:, output:, max_diff_lines: 50)
+      def initialize(schema_definition_results:, schema_artifacts_directory:, output:, extension_artifact_options: {}, max_diff_lines: 50)
         @schema_definition_results = schema_definition_results
         @schema_artifacts_directory = schema_artifacts_directory
-        @enforce_json_schema_version = enforce_json_schema_version
+        @extension_artifact_options = extension_artifact_options
         @output = output
         @max_diff_lines = max_diff_lines
 
@@ -51,7 +51,7 @@ def initialize(schema_definition_results:, schema_artifacts_directory:, enforce_
       # Dumps all the schema artifacts to disk.
       def dump_artifacts
         check_if_needs_json_schema_version_bump do |recommended_json_schema_version|
-          if @enforce_json_schema_version
+          if @extension_artifact_options.fetch(:enforce_json_schema_version, true)
             # @type var setter_location: ::Thread::Backtrace::Location
             # We use `_ =` because while `json_schema_version_setter_location` can be nil,
             # it'll never be nil if we get here and we want the type to be non-nilable.
@@ -62,8 +62,9 @@ def dump_artifacts
               "increase the schema's version, and then run the `bundle exec rake schema_artifacts:dump` command again.\n\n" \
               "To update the schema version to the expected version, change line #{setter_location.lineno} at `#{setter_location_path}` to:\n" \
               "  `schema.json_schema_version #{recommended_json_schema_version}`\n\n" \
-              "Alternately, pass `enforce_json_schema_version: false` to `ElasticGraph::SchemaDefinition::RakeTasks.new` to allow the JSON schemas " \
-              "file to change without requiring a version bump, but that is only recommended for non-production applications during initial schema prototyping."
+              "Alternately, pass `extension_artifact_options: {enforce_json_schema_version: false}` to `ElasticGraph::SchemaDefinition::RakeTasks.new` " \
+              "to allow the JSON schemas file to change without requiring a version bump, but that is only recommended for non-production applications " \
+              "during initial schema prototyping."
           else
             @output.puts <<~EOS
               WARNING: the `json_schemas.yaml` artifact is being updated without the `json_schema_version` being correspondingly incremented.

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

@@ -7,8 +7,10 @@
 # frozen_string_literal: true
 
 require "elastic_graph/errors"
+require "elastic_graph/schema_artifacts/from_disk"
 require "elastic_graph/schema_artifacts/runtime_metadata/schema_element_names"
 require "elastic_graph/schema_definition/api"
+require "elastic_graph/schema_definition/extension_module_support"
 require "elastic_graph/schema_definition/schema_artifact_manager"
 
 module ElasticGraph
@@ -24,7 +26,7 @@ def define_schema(
         schema_element_name_overrides: {},
         index_document_sizes: true,
         json_schema_version: 1,
-        extension_modules: [],
+        extension_modules: ExtensionModuleSupport.default_extension_modules,
         derived_type_name_formats: {},
         type_name_overrides: {},
         enum_value_overrides_by_type: {},
@@ -55,7 +57,7 @@ def define_schema_with_schema_elements(
         schema_elements,
         index_document_sizes: true,
         json_schema_version: 1,
-        extension_modules: [],
+        extension_modules: ExtensionModuleSupport.default_extension_modules,
         derived_type_name_formats: {},
         type_name_overrides: {},
         enum_value_overrides_by_type: {},
@@ -76,7 +78,7 @@ def define_schema_with_schema_elements(
 
         # Set the json_schema_version to the provided value, if needed.
         if !json_schema_version.nil? && api.state.json_schema_version.nil?
-          api.json_schema_version json_schema_version
+          api.json_schema_version(json_schema_version)
         end
 
         # :nocov: -- the else branch and code past this aren't used by tests in elasticgraph-schema_definition.
@@ -88,7 +90,7 @@ def define_schema_with_schema_elements(
         artifacts_manager = api.factory.new_schema_artifact_manager(
           schema_definition_results: api.results,
           schema_artifacts_directory: tmp_dir,
-          enforce_json_schema_version: false,
+          extension_artifact_options: {enforce_json_schema_version: false},
           output: ::StringIO.new
         )
 

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/extension_module_support.rbs

@@ -0,0 +1,7 @@
+module ElasticGraph
+  module SchemaDefinition
+    module ExtensionModuleSupport
+      def self.default_extension_modules: () -> ::Array[::Module]
+    end
+  end
+end

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/factory.rbs

@@ -2,6 +2,7 @@ module ElasticGraph
   module SchemaDefinition
     class Factory
       @state: State
+      attr_reader state: State
       def initialize: (State) -> void
 
       def self.prevent_non_factory_instantiation_of: (::Class) -> ::Method
@@ -129,8 +130,8 @@ module ElasticGraph
       def new_schema_artifact_manager: (
         schema_definition_results: Results,
         schema_artifacts_directory: ::String,
-        enforce_json_schema_version: bool,
         output: io,
+        ?extension_artifact_options: ::Hash[::Symbol, untyped],
         ?max_diff_lines: ::Integer
       ) -> SchemaArtifactManager
       @@schema_artifact_manager_new: ::Method

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/rake_tasks.rbs

@@ -11,7 +11,7 @@ module ElasticGraph
         ?type_name_overrides: ::Hash[::Symbol, ::String],
         ?enum_value_overrides_by_type: ::Hash[::Symbol, ::Hash[::Symbol, ::String]],
         ?extension_modules: ::Array[::Module],
-        ?enforce_json_schema_version: bool,
+        ?extension_artifact_options: ::Hash[::Symbol, untyped],
         ?output: io
       ) -> void
 
@@ -24,7 +24,7 @@ module ElasticGraph
       @index_document_sizes: bool
       @path_to_schema: ::String | ::Pathname
       @schema_artifacts_directory: ::String | ::Pathname
-      @enforce_json_schema_version: bool
+      @extension_artifact_options: ::Hash[::Symbol, untyped]
       @extension_modules: ::Array[::Module]
       @output: io
 

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/schema_artifact_manager.rbs

@@ -6,8 +6,8 @@ module ElasticGraph
       def initialize: (
         schema_definition_results: Results,
         schema_artifacts_directory: ::String,
-        enforce_json_schema_version: bool,
         output: io,
+        ?extension_artifact_options: ::Hash[::Symbol, untyped],
         ?max_diff_lines: ::Integer
       ) -> void
 
@@ -18,7 +18,7 @@ module ElasticGraph
 
       @schema_definition_results: Results
       @schema_artifacts_directory: ::String
-      @enforce_json_schema_version: bool
+      @extension_artifact_options: ::Hash[::Symbol, untyped]
       @output: io
       @max_diff_lines: ::Integer
       @artifacts: ::Array[SchemaArtifact[untyped]]?

elasticgraph-schema_definition/sig/elastic_graph/schema_definition/test_support.rbs

@@ -12,7 +12,7 @@ module ElasticGraph
         ?enum_value_overrides_by_type: ::Hash[::Symbol, ::Hash[::Symbol, ::String]],
         ?output: io?,
         ?reload_schema_artifacts: bool,
-      ) ?{ (API) -> void } -> _SchemaArtifacts
+      ) ?{ (API) -> void } -> (Results | SchemaArtifacts::FromDisk)
 
       def define_schema_with_schema_elements: (
         SchemaArtifacts::RuntimeMetadata::SchemaElementNames,
@@ -24,7 +24,7 @@ module ElasticGraph
         ?enum_value_overrides_by_type: ::Hash[::Symbol, ::Hash[::Symbol, ::String]],
         ?output: io?,
         ?reload_schema_artifacts: bool,
-      ) ?{ (API) -> void } -> _SchemaArtifacts
+      ) ?{ (API) -> void } -> (Results | SchemaArtifacts::FromDisk)
 
       DOC_COMMENTS: ::String
 

elasticgraph-schema_definition/spec/integration/elastic_graph/schema_definition/rake_tasks_spec.rb

@@ -859,7 +859,7 @@ module SchemaDefinition
               index_document_sizes: true,
               path_to_schema: "\#{project_root}/config/schema.rb",
               schema_artifacts_directory: "\#{project_root}/config/schema/artifacts",
-              enforce_json_schema_version: false
+              extension_artifact_options: {enforce_json_schema_version: false}
             )
           EOS
 
@@ -1086,8 +1086,8 @@ def as_active_instance
             index_document_sizes: true,
             path_to_schema: path_to_schema,
             schema_artifacts_directory: "config/schema/artifacts",
-            enforce_json_schema_version: enforce_json_schema_version,
-            extension_modules: [extension_module].compact,
+            extension_artifact_options: {enforce_json_schema_version: enforce_json_schema_version},
+            extension_modules: ::ElasticGraph::SchemaDefinition::ExtensionModuleSupport.default_extension_modules + [extension_module].compact,
             derived_type_name_formats: derived_type_name_formats,
             type_name_overrides: type_name_overrides,
             enum_value_overrides_by_type: enum_value_overrides_by_type,

elasticgraph-warehouse/spec/integration/elastic_graph/warehouse/schema_definition/rake_tasks_spec.rb

@@ -184,8 +184,8 @@ def run_rake_with_warehouse(*args, enforce_json_schema_version: true)
               index_document_sizes: false,
               path_to_schema: "schema.rb",
               schema_artifacts_directory: "config/schema/artifacts",
-              enforce_json_schema_version: enforce_json_schema_version,
-              extension_modules: [Warehouse::SchemaDefinition::APIExtension],
+              extension_artifact_options: {enforce_json_schema_version: enforce_json_schema_version},
+              extension_modules: ::ElasticGraph::SchemaDefinition::ExtensionModuleSupport.default_extension_modules + [Warehouse::SchemaDefinition::APIExtension],
               output: output
             )
           end