elasticgraph-schema_definition 0.18.0.0

data/lib/elastic_graph/schema_definition/schema_elements/relationship.rb

@@ -0,0 +1,218 @@
+# Copyright 2024 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
+
+require "delegate"
+require "elastic_graph/error"
+require "elastic_graph/schema_definition/schema_elements/field"
+require "elastic_graph/support/hash_util"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Wraps a {Field} to provide additional relationship-specific functionality when defining a field via
+      # {TypeWithSubfields#relates_to_one} or {TypeWithSubfields#relates_to_many}.
+      #
+      # @example Define relationships between two types
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.object_type "Orchestra" do |t|
+      #       t.field "id", "ID"
+      #       t.relates_to_many "musicians", "Musician", via: "orchestraId", dir: :in, singular: "musician" do |r|
+      #         # In this block, `r` is a `Relationship`.
+      #       end
+      #       t.index "orchestras"
+      #     end
+      #
+      #     schema.object_type "Musician" do |t|
+      #       t.field "id", "ID"
+      #       t.field "instrument", "String"
+      #       t.relates_to_one "orchestra", "Orchestra", via: "orchestraId", dir: :out do |r|
+      #         # In this block, `r` is a `Relationship`.
+      #       end
+      #       t.index "musicians"
+      #     end
+      #   end
+      class Relationship < DelegateClass(Field)
+        # @dynamic related_type
+
+        # @return [ObjectType, InterfaceType, UnionType] the type this relationship relates to
+        attr_reader :related_type
+
+        # @private
+        def initialize(field, cardinality:, related_type:, foreign_key:, direction:)
+          super(field)
+          @cardinality = cardinality
+          @related_type = related_type
+          @foreign_key = foreign_key
+          @direction = direction
+          @equivalent_field_paths_by_local_path = {}
+          @additional_filter = {}
+        end
+
+        # Adds additional filter conditions to a relationship beyond the foreign key.
+        #
+        # @param filter [Hash<Symbol, Object>, Hash<String, Object>] additional filter conditions for this relationship
+        # @return [void]
+        #
+        # @example Define additional filter conditions on a `relates_to_one` relationship
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Orchestra" do |t|
+        #       t.field "id", "ID"
+        #       t.relates_to_many "musicians", "Musician", via: "orchestraId", dir: :in, singular: "musician"
+        #       t.relates_to_one "firstViolin", "Musician", via: "orchestraId", dir: :in do |r|
+        #         r.additional_filter isFirstViolon: true
+        #       end
+        #
+        #       t.index "orchestras"
+        #     end
+        #
+        #     schema.object_type "Musician" do |t|
+        #       t.field "id", "ID"
+        #       t.field "instrument", "String"
+        #       t.field "isFirstViolon", "Boolean"
+        #       t.relates_to_one "orchestra", "Orchestra", via: "orchestraId", dir: :out
+        #       t.index "musicians"
+        #     end
+        #   end
+        def additional_filter(filter)
+          stringified_filter = Support::HashUtil.stringify_keys(filter)
+          @additional_filter = Support::HashUtil.deep_merge(@additional_filter, stringified_filter)
+        end
+
+        # Indicates that `path` (a field on the related type) is the equivalent of `locally_named` on this type.
+        #
+        # Use this API to specify a local field's equivalent path on the related type. This must be used on relationships used by
+        # {Field#sourced_from} when the local type uses {Indexing::Index#route_with} or {Indexing::Index#rollover} so that
+        # ElasticGraph can determine what field from the related type to use to route the update requests to the correct index and shard.
+        #
+        # @param path [String] path to a routing or rollover field on the related type
+        # @param locally_named [String] path on the local type to the equivalent field
+        # @return [void]
+        #
+        # @example
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID!"
+        #       t.field "name", "String"
+        #       t.field "createdAt", "DateTime"
+        #
+        #       t.relates_to_one "launchPlan", "CampaignLaunchPlan", via: "campaignId", dir: :in do |r|
+        #         r.equivalent_field "campaignCreatedAt", locally_named: "createdAt"
+        #       end
+        #
+        #       t.field "launchDate", "Date" do |f|
+        #         f.sourced_from "launchPlan", "launchDate"
+        #       end
+        #
+        #       t.index "campaigns"do |i|
+        #         i.rollover :yearly, "createdAt"
+        #       end
+        #     end
+        #
+        #     schema.object_type "CampaignLaunchPlan" do |t|
+        #       t.field "id", "ID"
+        #       t.field "campaignId", "ID"
+        #       t.field "campaignCreatedAt", "DateTime"
+        #       t.field "launchDate", "Date"
+        #
+        #       t.index "campaign_launch_plans"
+        #     end
+        #   end
+        def equivalent_field(path, locally_named: path)
+          if @equivalent_field_paths_by_local_path.key?(locally_named)
+            raise SchemaError, "`equivalent_field` has been called multiple times on `#{parent_type.name}.#{name}` with the same " \
+              "`locally_named` value (#{locally_named.inspect}), but each local field can have only one `equivalent_field`."
+          else
+            @equivalent_field_paths_by_local_path[locally_named] = path
+          end
+        end
+
+        # Gets the `routing_value_source` from this relationship for the given `index`, based on the configured
+        # routing used by `index` and the configured equivalent fields.
+        #
+        # Returns the GraphQL field name (not the `name_in_index`).
+        #
+        # @private
+        def routing_value_source_for_index(index)
+          return nil unless index.uses_custom_routing?
+
+          @equivalent_field_paths_by_local_path.fetch(index.routing_field_path.path) do |local_need|
+            yield local_need
+          end
+        end
+
+        # Gets the `rollover_timestamp_value_source` from this relationship for the given `index`, based on the
+        # configured equivalent fields and the rollover configuration used by `index`.
+        #
+        # Returns the GraphQL field name (not the `name_in_index`).
+        #
+        # @private
+        def rollover_timestamp_value_source_for_index(index)
+          return nil unless (rollover_config = index.rollover_config)
+
+          @equivalent_field_paths_by_local_path.fetch(rollover_config.timestamp_field_path.path) do |local_need|
+            yield local_need
+          end
+        end
+
+        # @private
+        def validate_equivalent_fields(field_path_resolver)
+          resolved_related_type = (_ = related_type.as_object_type) # : indexableType
+
+          @equivalent_field_paths_by_local_path.flat_map do |local_path_string, related_type_path_string|
+            errors = [] # : ::Array[::String]
+
+            local_path = resolve_and_validate_field_path(parent_type, local_path_string, field_path_resolver) do |error|
+              errors << error
+            end
+
+            related_type_path = resolve_and_validate_field_path(resolved_related_type, related_type_path_string, field_path_resolver) do |error|
+              errors << error
+            end
+
+            if local_path && related_type_path && local_path.type.unwrap_non_null != related_type_path.type.unwrap_non_null
+              errors << "Field `#{related_type_path.full_description}` is defined as an equivalent of " \
+                "`#{local_path.full_description}` via an `equivalent_field` definition on `#{parent_type.name}.#{name}`, " \
+                "but their types do not agree. To continue, change one or the other so that they agree."
+            end
+
+            errors
+          end
+        end
+
+        # @private
+        def many?
+          @cardinality == :many
+        end
+
+        # @private
+        def runtime_metadata
+          field_path_resolver = SchemaElements::FieldPath::Resolver.new
+          resolved_related_type = (_ = related_type.unwrap_list.as_object_type) # : indexableType
+          foreign_key_nested_paths = field_path_resolver.determine_nested_paths(resolved_related_type, @foreign_key)
+          foreign_key_nested_paths ||= [] # : ::Array[::String]
+          SchemaArtifacts::RuntimeMetadata::Relation.new(foreign_key: @foreign_key, direction: @direction, additional_filter: @additional_filter, foreign_key_nested_paths: foreign_key_nested_paths)
+        end
+
+        private
+
+        def resolve_and_validate_field_path(type, field_path_string, field_path_resolver)
+          field_path = field_path_resolver.resolve_public_path(type, field_path_string) do |parent_field|
+            !parent_field.type.list?
+          end
+
+          if field_path.nil?
+            yield "Field `#{type.name}.#{field_path_string}` (referenced from an `equivalent_field` defined on " \
+              "`#{parent_type.name}.#{name}`) does not exist. Either define it or correct the `equivalent_field` definition."
+          end
+
+          field_path
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/scalar_type.rb

@@ -0,0 +1,310 @@
+# Copyright 2024 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
+
+require "elastic_graph/schema_artifacts/runtime_metadata/scalar_type"
+require "elastic_graph/schema_definition/indexing/field_type/scalar"
+require "elastic_graph/schema_definition/mixins/can_be_graphql_only"
+require "elastic_graph/schema_definition/mixins/has_derived_graphql_type_customizations"
+require "elastic_graph/schema_definition/mixins/has_directives"
+require "elastic_graph/schema_definition/mixins/has_documentation"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/mixins/has_type_info"
+require "elastic_graph/schema_definition/mixins/verifies_graphql_name"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # {include:API#scalar_type}
+      #
+      # @example Define a scalar type
+      #   ElasticGraph.define_schema do |schema|
+      #     schema.scalar_type "URL" do |t|
+      #       t.mapping type: "keyword"
+      #       t.json_schema type: "string", format: "uri"
+      #     end
+      #   end
+      #
+      # @!attribute [r] schema_def_state
+      #   @return [State] schema definition state
+      # @!attribute [rw] type_ref
+      #   @private
+      # @!attribute [rw] mapping_type
+      #   @private
+      # @!attribute [rw] runtime_metadata
+      #   @private
+      # @!attribute [rw] aggregated_values_customizations
+      #   @private
+      class ScalarType < Struct.new(:schema_def_state, :type_ref, :mapping_type, :runtime_metadata, :aggregated_values_customizations)
+        # `Struct.new` provides the following methods:
+        # @dynamic type_ref, runtime_metadata
+        prepend Mixins::VerifiesGraphQLName
+        include Mixins::CanBeGraphQLOnly
+        include Mixins::HasDocumentation
+        include Mixins::HasDirectives
+        include Mixins::HasDerivedGraphQLTypeCustomizations
+        include Mixins::HasReadableToSAndInspect.new { |t| t.name }
+
+        # `HasTypeInfo` provides the following methods:
+        # @dynamic mapping_options, json_schema_options
+        include Mixins::HasTypeInfo
+
+        # @dynamic graphql_only?
+
+        # @private
+        def initialize(schema_def_state, name)
+          super(schema_def_state, schema_def_state.type_ref(name).to_final_form)
+
+          # Default the runtime metadata before yielding, so it can be overridden as needed.
+          self.runtime_metadata = SchemaArtifacts::RuntimeMetadata::ScalarType.new(
+            coercion_adapter_ref: SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_COERCION_ADAPTER_REF,
+            indexing_preparer_ref: SchemaArtifacts::RuntimeMetadata::ScalarType::DEFAULT_INDEXING_PREPARER_REF
+          )
+
+          yield self
+
+          missing = [
+            ("`mapping`" if mapping_options.empty?),
+            ("`json_schema`" if json_schema_options.empty?)
+          ].compact
+
+          if missing.any?
+            raise SchemaError, "Scalar types require `mapping` and `json_schema` to be configured, but `#{name}` lacks #{missing.join(" and ")}."
+          end
+        end
+
+        # @return [String] name of the scalar type
+        def name
+          type_ref.name
+        end
+
+        # (see Mixins::HasTypeInfo#mapping)
+        def mapping(**options)
+          self.mapping_type = options.fetch(:type) do
+            raise SchemaError, "Must specify a mapping `type:` on custom scalars but was missing on the `#{name}` type."
+          end
+
+          super
+        end
+
+        # Specifies the scalar coercion adapter that should be used for this scalar type. The scalar coercion adapter is responsible
+        # for validating and coercing scalar input values, and converting scalar return values to a form suitable for JSON serialization.
+        #
+        # @note For examples of scalar coercion adapters, see `ElasticGraph::GraphQL::ScalarCoercionAdapters`.
+        # @note If the `defined_at` require path requires any directories be put on the Ruby `$LOAD_PATH`, you are responsible for doing
+        #   that before booting {ElasticGraph::GraphQL}.
+        #
+        # @param adapter_name [String] fully qualified Ruby class name of the adapter
+        # @param defined_at [String] the `require` path of the adapter
+        # @return [void]
+        #
+        # @example Register a coercion adapter
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.scalar_type "PhoneNumber" do |t|
+        #       t.mapping type: "keyword"
+        #       t.json_schema type: "string", pattern: "^\\+[1-9][0-9]{1,14}$"
+        #       t.coerce_with "CoercionAdapters::PhoneNumber", defined_at: "./coercion_adapters/phone_number"
+        #     end
+        #   end
+        def coerce_with(adapter_name, defined_at:)
+          self.runtime_metadata = runtime_metadata.with(coercion_adapter_ref: {
+            "extension_name" => adapter_name,
+            "require_path" => defined_at
+          }).tap(&:load_coercion_adapter) # verify the adapter is valid.
+        end
+
+        # Specifies an indexing preparer that should be used for this scalar type. The indexing preparer is responsible for preparing
+        # scalar values before indexing them, performing any desired formatting or normalization.
+        #
+        # @note For examples of scalar coercion adapters, see `ElasticGraph::Indexer::IndexingPreparers`.
+        # @note If the `defined_at` require path requires any directories be put on the Ruby `$LOAD_PATH`, you are responsible for doing
+        #   that before booting {ElasticGraph::GraphQL}.
+        #
+        # @param preparer_name [String] fully qualified Ruby class name of the indexing preparer
+        # @param defined_at [String] the `require` path of the preparer
+        # @return [void]
+        #
+        # @example Register an indexing preparer
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.scalar_type "PhoneNumber" do |t|
+        #       t.mapping type: "keyword"
+        #       t.json_schema type: "string", pattern: "^\\+[1-9][0-9]{1,14}$"
+        #
+        #       t.prepare_for_indexing_with "IndexingPreparers::PhoneNumber",
+        #         defined_at: "./indexing_preparers/phone_number"
+        #     end
+        #   end
+        def prepare_for_indexing_with(preparer_name, defined_at:)
+          self.runtime_metadata = runtime_metadata.with(indexing_preparer_ref: {
+            "extension_name" => preparer_name,
+            "require_path" => defined_at
+          }).tap(&:load_indexing_preparer) # verify the preparer is valid.
+        end
+
+        # @return [String] the GraphQL SDL form of this scalar
+        def to_sdl
+          "#{formatted_documentation}scalar #{name} #{directives_sdl}"
+        end
+
+        # Registers a block which will be used to customize the derived `*AggregatedValues` object type.
+        #
+        # @private
+        def customize_aggregated_values_type(&block)
+          self.aggregated_values_customizations = block
+        end
+
+        # @private
+        def aggregated_values_type
+          if aggregated_values_customizations
+            type_ref.as_aggregated_values
+          else
+            schema_def_state.type_ref("NonNumeric").as_aggregated_values
+          end
+        end
+
+        # @private
+        def to_indexing_field_type
+          Indexing::FieldType::Scalar.new(scalar_type: self)
+        end
+
+        # @private
+        def derived_graphql_types
+          return [] if graphql_only?
+
+          pagination_types =
+            if schema_def_state.paginated_collection_element_types.include?(name)
+              schema_def_state.factory.build_relay_pagination_types(name, include_total_edge_count: true)
+            else
+              [] # : ::Array[ObjectType]
+            end
+
+          (to_input_filters + pagination_types).tap do |derived_types|
+            if (aggregated_values_type = to_aggregated_values_type)
+              derived_types << aggregated_values_type
+            end
+          end
+        end
+
+        # @private
+        def indexed?
+          false
+        end
+
+        private
+
+        EQUAL_TO_ANY_OF_DOC = <<~EOS
+          Matches records where the field value is equal to any of the provided values.
+          This works just like an IN operator in SQL.
+
+          Will be ignored when `null` is passed. When an empty list is passed, will cause this
+          part of the filter to match no documents. When `null` is passed in the list, will
+          match records where the field value is `null`.
+        EOS
+
+        GT_DOC = <<~EOS
+          Matches records where the field value is greater than (>) the provided value.
+
+          Will be ignored when `null` is passed.
+        EOS
+
+        GTE_DOC = <<~EOS
+          Matches records where the field value is greater than or equal to (>=) the provided value.
+
+          Will be ignored when `null` is passed.
+        EOS
+
+        LT_DOC = <<~EOS
+          Matches records where the field value is less than (<) the provided value.
+
+          Will be ignored when `null` is passed.
+        EOS
+
+        LTE_DOC = <<~EOS
+          Matches records where the field value is less than or equal to (<=) the provided value.
+
+          Will be ignored when `null` is passed.
+        EOS
+
+        def to_input_filters
+          # Note: all fields on inputs should be nullable, to support parameterized queries where
+          # the parameters are allowed to be set to `null`. We also now support nulls within lists.
+
+          # For floats, we may want to remove the `equal_to_any_of` operator at some point.
+          # In many languages. checking exact equality with floats is problematic.
+          # For example, in IRB:
+          #
+          # 2.7.1 :003 > 0.3 == (0.1 + 0.2)
+          # => false
+          #
+          # However, it's not yet clear if that issue will come up with GraphQL, because
+          # float values are serialized on the wire as JSON, using an exact decimal
+          # string representation. So for now we are keeping `equal_to_any_of`.
+          schema_def_state.factory.build_standard_filter_input_types_for_index_leaf_type(name) do |t|
+            # Normally, we use a nullable type for `equal_to_any_of`, to allow a filter expression like this:
+            #
+            # filter: {optional_field: {equal_to_any_of: [null]}}
+            #
+            # That filter expression matches documents where `optional_field == null`. However,
+            # we cannot support this:
+            #
+            # filter: {tags: {any_satisfy: {equal_to_any_of: [null]}}}
+            #
+            # We can't support that because we implement filtering on `null` using an `exists` query:
+            # https://www.elastic.co/guide/en/elasticsearch/reference/8.10/query-dsl-exists-query.html
+            #
+            # ...but that works based on the field existing (or not), and does not let us filter on the
+            # presence or absence of `null` within a list.
+            #
+            # So, here we make the field non-null if we're in an `any_satisfy` context (as indicated by
+            # the type ending with `ListElementFilterInput`).
+            equal_to_any_of_type = t.type_ref.list_element_filter_input? ? "[#{name}!]" : "[#{name}]"
+
+            t.field schema_def_state.schema_elements.equal_to_any_of, equal_to_any_of_type do |f|
+              f.documentation EQUAL_TO_ANY_OF_DOC
+            end
+
+            if mapping_type_efficiently_comparable?
+              t.field schema_def_state.schema_elements.gt, name do |f|
+                f.documentation GT_DOC
+              end
+
+              t.field schema_def_state.schema_elements.gte, name do |f|
+                f.documentation GTE_DOC
+              end
+
+              t.field schema_def_state.schema_elements.lt, name do |f|
+                f.documentation LT_DOC
+              end
+
+              t.field schema_def_state.schema_elements.lte, name do |f|
+                f.documentation LTE_DOC
+              end
+            end
+          end
+        end
+
+        def to_aggregated_values_type
+          return nil unless (customization_block = aggregated_values_customizations)
+          schema_def_state.factory.new_aggregated_values_type_for_index_leaf_type(name, &customization_block)
+        end
+
+        # https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping-types.html
+        # https://www.elastic.co/guide/en/elasticsearch/reference/7.13/number.html#number
+        NUMERIC_TYPES = %w[long integer short byte double float half_float scaled_float unsigned_long].to_set
+        DATE_TYPES = %w[date date_nanos].to_set
+        # The Elasticsearch/OpenSearch docs do not exhaustively give a list of types on which range queries are efficient,
+        # but the docs are clear that it is efficient on numeric and date types, and is inefficient on string
+        # types: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-range-query.html
+        COMPARABLE_TYPES = NUMERIC_TYPES | DATE_TYPES
+
+        def mapping_type_efficiently_comparable?
+          COMPARABLE_TYPES.include?(mapping_type)
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/sort_order_enum_value.rb

@@ -0,0 +1,36 @@
+# Copyright 2024 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
+
+require "delegate"
+require "elastic_graph/schema_definition/mixins/has_readable_to_s_and_inspect"
+require "elastic_graph/schema_definition/schema_elements/enum_value"
+
+module ElasticGraph
+  module SchemaDefinition
+    module SchemaElements
+      # Simple wrapper around an {EnumValue} so that we can expose the `sort_order_field_path` to {Field} customization callbacks.
+      class SortOrderEnumValue < DelegateClass(EnumValue)
+        include Mixins::HasReadableToSAndInspect.new { |v| v.name }
+
+        # @dynamic sort_order_field_path
+
+        # @return [Array<Field>] path to the field from the root of the indexed {ObjectType}
+        attr_reader :sort_order_field_path
+
+        # @private
+        def initialize(enum_value, sort_order_field_path)
+          # We've told steep that SortOrderEnumValue is subclass of EnumValue
+          # but here are supering to the `DelegateClass`'s initialize, not `EnumValue`'s,
+          # so we have to use `__skip__`
+          __skip__ = super(enum_value)
+          @sort_order_field_path = sort_order_field_path
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/schema_elements/sub_aggregation_path.rb

@@ -0,0 +1,66 @@
+# Copyright 2024 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
+    module SchemaElements
+      # Abstraction responsible for identifying paths to sub-aggregations, and, on that basis, determining
+      # what the type names should be.
+      #
+      # @private
+      SubAggregationPath = ::Data.define(
+        # List of index document types within which the target type exists. This contains the set of parent
+        # index document types--that is, types which are indexed or are themselves used as a `nested` field
+        # on a parent of it. Parent objects which are not "index documents" (e.g. directly at an index level
+        # or a nested field level) are omitted; we omit them because we don't offer sub-aggregations for such
+        # a field, and the set of sub-aggregations we are going to offer is the basis for generating separate
+        # `*SubAggregation` types.
+        :parent_doc_types,
+        # List of fields forming a path from the last parent doc type.
+        :field_path
+      ) do
+        # @implements SubAggregationPath
+
+        # Determines the set of sub aggregation paths for the given type.
+        def self.paths_for(type, schema_def_state:)
+          root_paths = type.indexed? ? [SubAggregationPath.new([type.name], [])] : [] # : ::Array[SubAggregationPath]
+
+          non_relation_field_refs = schema_def_state
+            .user_defined_field_references_by_type_name.fetch(type.name) { [] }
+            # Relationship fields are the only case where types can reference each other in circular fashion.
+            # If we don't reject that case here, we can get stuck in infinite recursion.
+            .reject(&:relationship)
+
+          root_paths + non_relation_field_refs.flat_map do |field_ref|
+            # Here we call `schema_def_state.sub_aggregation_paths_for` rather than directly
+            # recursing to give schema_def_state a chance to cache the results.
+            parent_paths = schema_def_state.sub_aggregation_paths_for(field_ref.parent_type)
+
+            if field_ref.nested?
+              parent_paths.map { |path| path.plus_parent(field_ref.type_for_derived_types.fully_unwrapped.name) }
+            else
+              parent_paths.map { |path| path.plus_field(field_ref) }
+            end
+          end
+        end
+
+        def plus_parent(parent)
+          with(parent_doc_types: parent_doc_types + [parent], field_path: [])
+        end
+
+        def plus_field(field)
+          with(field_path: field_path + [field])
+        end
+
+        def field_path_string
+          field_path.map(&:name).join(".")
+        end
+      end
+    end
+  end
+end