elasticgraph-schema_definition 1.0.2 → 1.0.3.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4756602b0f1d661da8c577effc6f1daa1ef0ad8cc86148f3068ebc13c676f6b8
-  data.tar.gz: 37a2c4e7901483d9a211a9dd16a00554f8fbf9e05ba02201202a40f587ffff68
+  metadata.gz: 9865f28d6f21c9522e9834f4bf583e563861fa6ee08f7a7c532588c6848853e0
+  data.tar.gz: d00543cabfa2cb9bbdbc225de3224cd16adee14fe50a559da63299deff50b658
 SHA512:
-  metadata.gz: cb4dd42e565f3635496d2f0df52390528814b9a0f56b9f702a910ffa850ab08a76179b088d0b72cbb08fe835e14551b26dfd4557b0e838dc482468596893417b
-  data.tar.gz: cda65f9354c0c726a53254213f11e211b59de7dd1639cf6bb158394c1af00a6de4666707d356101e1d7a0137f324ceb21606ce05ce7b977847098111f38b5589
+  metadata.gz: ffc146e35c36a4fe9010f16945ba8ecca2863cd22d0dd074d92f9b6abb428e1d318f10d1effce30506dc310714e12c34baa2420f36b2a499d28416db3742eca8
+  data.tar.gz: eefd1fa67fdf00e33eddb7b128953a0bf301d57894367be7b0dd525b67237e439ff239e40373e8a958d02dcc3b417c1a5f080ac72796146e1a0c29da136ad422

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2024 - 2025 Block, Inc.
+Copyright (c) 2024 - 2026 Block, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/lib/elastic_graph/schema_definition/api.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -387,7 +387,7 @@ module ElasticGraph
 
       # @return the results of the schema definition
       def results
-        @results ||= Results.new(@state)
+        @results ||= @factory.new_results
       end
 
       # Defines the version number of the current JSON schema. Importantly, every time a change is made that impacts the JSON schema
@@ -421,6 +421,38 @@ module ElasticGraph
         nil
       end
 
+      # Defines strictness of the JSON schema validation. By default, the JSON schema will require all fields to be provided by the
+      # publisher (but they can be nullable) and will ignore extra fields that are not defined in the schema. Use this method to
+      # configure this behavior.
+      #
+      # @param allow_omitted_fields [bool] Whether nullable fields can be omitted from indexing events.
+      # @param allow_extra_fields [bool] Whether extra fields (e.g. beyond fields defined in the schema) can be included in indexing events.
+      # @return [void]
+      #
+      # @note If you allow both omitted fields and extra fields, ElasticGraph's JSON schema validation will allow (and ignore) misspelled
+      #   field names in indexing events. For example, if the ElasticGraph schema has a nullable field named `parentId` but the publisher
+      #   accidentally provides it as `parent_id`, ElasticGraph would happily ignore the `parent_id` field entirely, because `parentId`
+      #   is allowed to be omitted and `parent_id` would be treated as an extra field. Therefore, we recommend that you only set one of
+      #   these to `true` (or none).
+      #
+      # @example Allow omitted fields and disallow extra fields
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.json_schema_strictness allow_omitted_fields: true, allow_extra_fields: false
+      #   end
+      def json_schema_strictness(allow_omitted_fields: false, allow_extra_fields: true)
+        unless [true, false].include?(allow_omitted_fields)
+          raise Errors::SchemaError, "`allow_omitted_fields` must be true or false"
+        end
+
+        unless [true, false].include?(allow_extra_fields)
+          raise Errors::SchemaError, "`allow_extra_fields` must be true or false"
+        end
+
+        @state.allow_omitted_json_schema_fields = allow_omitted_fields
+        @state.allow_extra_json_schema_fields = allow_extra_fields
+        nil
+      end
+
       # Registers a customization callback that will be applied to every built-in type automatically provided by ElasticGraph. Provides
       # an opportunity to customize the built-in types (e.g. to add directives to them or whatever).
       #

data/lib/elastic_graph/schema_definition/factory.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -8,6 +8,9 @@
 
 require "elastic_graph/constants"
 require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/results"
+require "elastic_graph/schema_definition/indexing/index"
+require "elastic_graph/schema_definition/schema_artifact_manager"
 require "elastic_graph/schema_definition/schema_elements/argument"
 require "elastic_graph/schema_definition/schema_elements/built_in_types"
 require "elastic_graph/schema_definition/schema_elements/deprecated_element"
@@ -275,6 +278,33 @@ module ElasticGraph
       end
       @@relationship_new = prevent_non_factory_instantiation_of(SchemaElements::Relationship)
 
+      def new_index(name, settings, type, &block)
+        @@index_new.call(name, settings, @state, type, &block)
+      end
+      @@index_new = prevent_non_factory_instantiation_of(Indexing::Index)
+
+      def new_results
+        @@results_new.call(@state)
+      end
+      @@results_new = prevent_non_factory_instantiation_of(Results)
+
+      def new_schema_artifact_manager(
+        schema_definition_results:,
+        schema_artifacts_directory:,
+        enforce_json_schema_version:,
+        output:,
+        max_diff_lines: 50
+      )
+        @@schema_artifact_manager_new.call(
+          schema_definition_results:,
+          schema_artifacts_directory:,
+          enforce_json_schema_version:,
+          output:,
+          max_diff_lines:
+        )
+      end
+      @@schema_artifact_manager_new = prevent_non_factory_instantiation_of(SchemaArtifactManager)
+
       # Responsible for creating a new `*AggregatedValues` type for an index leaf type.
       #
       # An index leaf type is a scalar, enum, object type that is backed by a single, indivisible

data/lib/elastic_graph/schema_definition/indexing/derived_fields/append_only_set.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/derived_fields/field_initializer_support.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/derived_fields/immutable_value.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/derived_fields/min_or_max_value.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/derived_indexed_type.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/event_envelope.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/field.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -28,7 +28,8 @@ module ElasticGraph
         :json_schema_customizations,
         :mapping_customizations,
         :source,
-        :runtime_field_script
+        :runtime_field_script,
+        :doc_comment
       )
         # JSON schema overrides that automatically apply to specific mapping types so that the JSON schema
         # validation will reject values which cannot be indexed into fields of a specific mapping type.
@@ -70,6 +71,7 @@ module ElasticGraph
             .reverse # resolve layers from innermost to outermost wrappings
             .reduce(inner_json_schema) { |acc, layer| process_layer(layer, acc) }
             .merge(outer_json_schema_customizations)
+            .merge({"description" => doc_comment}.compact)
             .then { |h| Support::HashUtil.stringify_keys(h) }
         end
 
@@ -106,6 +108,10 @@ module ElasticGraph
           mapping_hash
         end
 
+        def nullable?
+          json_schema_layers.include?(:nullable)
+        end
+
         private
 
         def inner_json_schema

data/lib/elastic_graph/schema_definition/indexing/field_reference.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -18,7 +18,8 @@ module ElasticGraph
         :json_schema_options,
         :accuracy_confidence,
         :source,
-        :runtime_field_script
+        :runtime_field_script,
+        :doc_comment
       )
 
       # A lazy reference to a {Field}. It contains all attributes needed to build a {Field}, but the referenced `type` may not be
@@ -40,11 +41,12 @@ module ElasticGraph
             json_schema_customizations: json_schema_options,
             mapping_customizations: mapping_options,
             source: source,
-            runtime_field_script: runtime_field_script
+            runtime_field_script: runtime_field_script,
+            doc_comment: doc_comment
           )
         end
 
-        # @dynamic initialize, with, name, name_in_index, type, mapping_options, json_schema_options, accuracy_confidence, source, runtime_field_script
+        # @dynamic initialize, with, name, name_in_index, type, mapping_options, json_schema_options, accuracy_confidence, source, runtime_field_script, doc_comment
       end
     end
   end

data/lib/elastic_graph/schema_definition/indexing/field_type/enum.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/field_type/object.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -24,9 +24,11 @@ module ElasticGraph
         #   @return [Hash<String, ::Object>] options to be included in the mapping
         # @!attribute [r] json_schema_options
         #   @return [Hash<String, ::Object>] options to be included in the JSON schema
+        # @!attribute [r] doc_comment
+        #   @return [String, nil] documentation for the type
         #
         # @api private
-        class Object < Support::MemoizableData.define(:type_name, :subfields, :mapping_options, :json_schema_options)
+        class Object < Support::MemoizableData.define(:schema_def_state, :type_name, :subfields, :mapping_options, :json_schema_options, :doc_comment)
           # @return [Hash<String, ::Object>] the datastore mapping for this object type.
           def to_mapping
             @to_mapping ||= begin
@@ -48,6 +50,8 @@ module ElasticGraph
                 other_source_subfields, json_schema_candidate_subfields = subfields.partition(&:source)
                 validate_sourced_fields_have_no_json_schema_overrides(other_source_subfields)
                 json_schema_subfields = json_schema_candidate_subfields.reject(&:runtime_field_script)
+                required_fields = json_schema_subfields
+                required_fields = required_fields.reject(&:nullable?) if schema_def_state.allow_omitted_json_schema_fields
 
                 {
                   "type" => "object",
@@ -55,8 +59,10 @@ module ElasticGraph
                   # Note: `__typename` is intentionally not included in the `required` list. If `__typename` is present
                   # we want it validated (as we do by merging in `json_schema_typename_field`) but we only want
                   # to require it in the context of a union type. The union's json schema requires the field.
-                  "required" => json_schema_subfields.map(&:name).freeze
-                }.freeze
+                  "required" => required_fields.map(&:name).freeze,
+                  "additionalProperties" => (false unless schema_def_state.allow_extra_json_schema_fields),
+                  "description" => doc_comment
+                }.compact.freeze
               else
                 Support::HashUtil.stringify_keys(json_schema_options)
               end

data/lib/elastic_graph/schema_definition/indexing/field_type/scalar.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/field_type/union.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/index.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -36,7 +36,9 @@ module ElasticGraph
       #   @return [Array<String>] path to the field used for shard routing
       # @!attribute [r] rollover_config
       #   @return [RolloverConfig, nil] rollover configuration for the index
-      class Index < Struct.new(:name, :default_sort_pairs, :settings, :schema_def_state, :indexed_type, :routing_field_path, :rollover_config)
+      # @!attribute [r] has_had_multiple_sources_flag
+      #   @return [Boolean] whether this index has ever had multiple sources
+      class Index < Struct.new(:name, :default_sort_pairs, :settings, :schema_def_state, :indexed_type, :routing_field_path, :rollover_config, :has_had_multiple_sources_flag)
         include Mixins::HasReadableToSAndInspect.new { |i| i.name }
 
         # @param name [String] name of the index
@@ -53,7 +55,7 @@ module ElasticGraph
 
           settings = DEFAULT_SETTINGS.merge(Support::HashUtil.flatten_and_stringify_keys(settings, prefix: "index"))
 
-          super(name, [], settings, schema_def_state, indexed_type, nil, nil)
+          super(name, [], settings, schema_def_state, indexed_type, nil, nil, false)
 
           schema_def_state.after_user_definition_complete do
             # `id` is the field Elasticsearch/OpenSearch use for routing by default:
@@ -188,6 +190,38 @@ module ElasticGraph
           end
         end
 
+        # Declares that this index has had (or currently has) multiple sources. This should be called when using
+        # `sourced_from` fields on an indexed type, as it indicates that the index may contain incomplete documents.
+        # Once set, this flag should remain set even if all `sourced_from` fields are later removed, because the index
+        # may still contain historical incomplete documents.
+        #
+        # @return [void]
+        #
+        # @example Declare that the index has had multiple sources
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Widget" do |t|
+        #       t.field "id", "ID!"
+        #       t.relates_to_one "owner", "Owner", via: "widget_ids", dir: :in
+        #       t.field "owner_name", "String" do |f|
+        #         f.sourced_from "owner", "name"
+        #       end
+        #
+        #       t.index "widgets" do |i|
+        #         i.has_had_multiple_sources!
+        #       end
+        #     end
+        #
+        #     schema.object_type "Owner" do |t|
+        #       t.field "id", "ID!"
+        #       t.field "name", "String"
+        #       t.field "widget_ids", "[ID!]!"
+        #       t.index "owners"
+        #     end
+        #   end
+        def has_had_multiple_sources!
+          self.has_had_multiple_sources_flag = true
+        end
+
         # @see #route_with
         # @return [Boolean] whether or not this index uses custom shard routing
         def uses_custom_routing?
@@ -227,7 +261,8 @@ module ElasticGraph
                 field_path: public_field_path(graphql_field_path_name, explanation: "it is referenced as an index `default_sort` field").path_in_index,
                 direction: direction
               )
-            end
+            end,
+            has_had_multiple_sources: has_had_multiple_sources_flag
           )
         end
 

data/lib/elastic_graph/schema_definition/indexing/json_schema_field_metadata.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/json_schema_with_metadata.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/list_counts_mapping.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/relationship_resolver.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/rollover_config.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/update_target_factory.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/indexing/update_target_resolver.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/json_schema_pruner.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/can_be_graphql_only.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_derived_graphql_type_customizations.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_directives.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_documentation.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_indices.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -77,7 +77,7 @@ module ElasticGraph
               "Only one index per type is supported. An index named `#{@index_def.name}` has already been defined."
           end
 
-          @index_def = Indexing::Index.new(name, settings, schema_def_state, self, &block)
+          @index_def = schema_def_state.factory.new_index(name, settings, self, &block)
         end
 
         # Configures the default GraphQL resolver that will be used to resolve the fields of this type. Individual fields

data/lib/elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_subtypes.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/has_type_info.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/implements_interfaces.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/supports_default_value.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/supports_filtering_and_aggregation.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/mixins/verifies_graphql_name.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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

data/lib/elastic_graph/schema_definition/rake_tasks.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -155,14 +155,14 @@ module ElasticGraph
       end
 
       def schema_artifact_manager
-        require "elastic_graph/schema_definition/schema_artifact_manager"
+        require "elastic_graph/schema_definition/api"
 
         # :nocov: -- tests don't cover the `VERBOSE` side
         max_diff_lines = ENV["VERBOSE"] ? 999999999 : 50
         # :nocov:
 
-        SchemaArtifactManager.new(
-          schema_definition_results: schema_definition_results,
+        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,
           output: @output,
@@ -170,7 +170,7 @@ module ElasticGraph
         )
       end
 
-      def schema_definition_results
+      def schema_def_api
         require "elastic_graph/schema_definition/api"
 
         API.new(
@@ -183,7 +183,7 @@ module ElasticGraph
           output: @output
         ).tap do |api|
           api.as_active_instance { load @path_to_schema.to_s }
-        end.results
+        end
       end
     end
   end

data/lib/elastic_graph/schema_definition/results.rb

@@ -1,4 +1,4 @@
-# Copyright 2024 - 2025 Block, Inc.
+# 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
@@ -18,6 +18,7 @@ require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
 require "elastic_graph/schema_definition/schema_elements/field_path"
 require "elastic_graph/schema_definition/scripting/file_system_repository"
 require "elastic_graph/support/memoizable_data"
+require "elastic_graph/version"
 
 module ElasticGraph
   module SchemaDefinition
@@ -225,6 +226,7 @@ module ElasticGraph
         end
 
         SchemaArtifacts::RuntimeMetadata::Schema.new(
+          elasticgraph_version: ElasticGraph::VERSION,
           object_types_by_name: object_types_by_name,
           scalar_types_by_name: scalar_types_by_name,
           enum_types_by_name: enum_types_by_name,
@@ -285,6 +287,15 @@ module ElasticGraph
               update_target, errors = update_target_resolver.resolve
               accum[resolved_relationship.related_type.name] << update_target if update_target
               sourced_field_errors.concat(errors)
+
+              # Validate that has_had_multiple_sources! has been called when sourced_from is used
+              if (index_def = object_type.index_def) && !index_def.has_had_multiple_sources_flag
+                sourced_field_errors << "Type `#{object_type.name}` uses `sourced_from` fields but its index `#{index_def.name}` " \
+                  "has not been configured with `has_had_multiple_sources!`. To resolve this, add `i.has_had_multiple_sources!` within the " \
+                  "`t.index \"#{index_def.name}\"` block. This flag is required because indices with multiple sources can contain " \
+                  "incomplete documents, and ElasticGraph needs to know this to apply proper filtering. Once set, this flag should remain even " \
+                  "if you later remove all `sourced_from` fields, as the index may still contain historical incomplete documents."
+              end
             end
           end
         end.tap do