elasticgraph-schema_definition 0.18.0.0

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

@@ -0,0 +1,96 @@
+# 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 Indexing
+      # @private
+      class RelationshipResolver
+        def initialize(schema_def_state:, object_type:, relationship_name:, sourced_fields:, field_path_resolver:)
+          @schema_def_state = schema_def_state
+          @object_type = object_type
+          @relationship_name = relationship_name
+          @sourced_fields = sourced_fields
+          @field_path_resolver = field_path_resolver
+        end
+
+        def resolve
+          relation_field = object_type.graphql_fields_by_name[relationship_name]
+
+          if relation_field.nil?
+            [nil, "#{relationship_error_prefix} is not defined. Is it misspelled?"]
+          elsif (relationship = relation_field.relationship).nil?
+            [nil, "#{relationship_error_prefix} is not a relationship. It must be defined using `relates_to_one` or `relates_to_many`."]
+          elsif (related_type = schema_def_state.object_types_by_name[relationship.related_type.unwrap_non_null.name]).nil?
+            issue =
+              if schema_def_state.types_by_name.key?(relationship.related_type.fully_unwrapped.name)
+                "references a type which is not an object type: `#{relationship.related_type.name}`. Only object types can be used in relations."
+              else
+                "references an unknown type: `#{relationship.related_type.name}`. Is it misspelled?"
+              end
+
+            [nil, "#{relationship_error_prefix} #{issue}"]
+          elsif !related_type.indexed?
+            [nil, "#{relationship_error_prefix} references a type which is not indexed: `#{related_type.name}`. Only indexed types can be used in relations."]
+          else
+            relation_metadata = relation_field.runtime_metadata_graphql_field.relation # : SchemaArtifacts::RuntimeMetadata::Relation
+            foreign_key_parent_type = (relation_metadata.direction == :in) ? related_type : object_type
+
+            if (foreign_key_error = validate_foreign_key(foreign_key_parent_type, relation_metadata))
+              [nil, foreign_key_error]
+            else
+              [ResolvedRelationship.new(relationship_name, relation_field, relationship, related_type, relation_metadata), nil]
+            end
+          end
+        end
+
+        private
+
+        # @dynamic schema_def_state, object_type, relationship_name, sourced_fields, field_path_resolver
+        attr_reader :schema_def_state, :object_type, :relationship_name, :sourced_fields, :field_path_resolver
+
+        # Helper method for building the prefix of relationship-related error messages.
+        def relationship_error_prefix
+          sourced_fields_description =
+            if sourced_fields.empty?
+              ""
+            else
+              " (referenced from `sourced_from` on field(s): #{sourced_fields.map { |f| "`#{f.name}`" }.join(", ")})"
+            end
+
+          "`#{relationship_description}`#{sourced_fields_description}"
+        end
+
+        def validate_foreign_key(foreign_key_parent_type, relation_metadata)
+          foreign_key_field = field_path_resolver.resolve_public_path(foreign_key_parent_type, relation_metadata.foreign_key) { true }
+          # If its an inbound foreign key, verify that the foreign key exists on the related type.
+          # Note: we don't verify this for outbound foreign keys, because when we define a relationship with an outbound foreign
+          # key, we automatically define an indexing only field for the foreign key (since it exists on the same type). We don't
+          # do that for an inbound foreign key, though (since the foreign key exists on another type). Allowing a relationship
+          # definition on type A to add a field to type B's schema would be weird and surprising.
+          if relation_metadata.direction == :in && foreign_key_field.nil?
+            "#{relationship_error_prefix} uses `#{foreign_key_parent_type.name}.#{relation_metadata.foreign_key}` as the foreign key, " \
+              "but that field does not exist as an indexing field. To continue, define it, define a relationship on `#{foreign_key_parent_type.name}` " \
+              "that uses it as the foreign key, use another field as the foreign key, or remove the `#{relationship_description}` definition."
+          elsif foreign_key_field && foreign_key_field.type.fully_unwrapped.name != "ID"
+            "#{relationship_error_prefix} uses `#{foreign_key_field.fully_qualified_path}` as the foreign key, " \
+              "but that field is not an `ID` field as expected. To continue, change it's type, use another field " \
+              "as the foreign key, or remove the `#{relationship_description}` definition."
+          end
+        end
+
+        def relationship_description
+          "#{object_type.name}.#{relationship_name}"
+        end
+      end
+
+      # @private
+      ResolvedRelationship = ::Data.define(:relationship_name, :relationship_field, :relationship, :related_type, :relation_metadata)
+    end
+  end
+end

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

@@ -0,0 +1,25 @@
+# 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/index_definition"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Indexing
+      # @private
+      class RolloverConfig < ::Data.define(:frequency, :timestamp_field_path)
+        def runtime_metadata
+          SchemaArtifacts::RuntimeMetadata::IndexDefinition::Rollover.new(
+            frequency: frequency,
+            timestamp_field_path: timestamp_field_path.path_in_index
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,54 @@
+# 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 Indexing
+      # Helper class that contains common logic for instantiating `UpdateTargets`.
+      # @private
+      module UpdateTargetFactory
+        def self.new_normal_indexing_update_target(
+          type:,
+          relationship:,
+          id_source:,
+          data_params:,
+          routing_value_source:,
+          rollover_timestamp_value_source:
+        )
+          SchemaArtifacts::RuntimeMetadata::UpdateTarget.new(
+            type: type,
+            relationship: relationship,
+            script_id: INDEX_DATA_UPDATE_SCRIPT_ID,
+            id_source: id_source,
+            metadata_params: standard_metadata_params.merge({
+              "relationship" => SchemaArtifacts::RuntimeMetadata::StaticParam.new(value: relationship)
+            }),
+            data_params: data_params,
+            routing_value_source: routing_value_source,
+            rollover_timestamp_value_source: rollover_timestamp_value_source
+          )
+        end
+
+        private_class_method def self.standard_metadata_params
+          @standard_metadata_params ||= {
+            "sourceId" => single_value_param_from("id"),
+            "sourceType" => single_value_param_from("type"),
+            "version" => single_value_param_from("version")
+          }
+        end
+
+        private_class_method def self.single_value_param_from(source_path)
+          SchemaArtifacts::RuntimeMetadata::DynamicParam.new(
+            source_path: source_path,
+            cardinality: :one
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,195 @@
+# 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/params"
+require "elastic_graph/schema_definition/indexing/update_target_factory"
+
+module ElasticGraph
+  module SchemaDefinition
+    module Indexing
+      # Responsible for resolving a relationship and a set of `sourced_from` fields into an `UpdateTarget`
+      # that contains the instructions for how the primary type should be updated from the related type's
+      # source events.
+      #
+      # @private
+      class UpdateTargetResolver
+        def initialize(
+          object_type:,
+          resolved_relationship:,
+          sourced_fields:,
+          field_path_resolver:
+        )
+          @object_type = object_type
+          @resolved_relationship = resolved_relationship
+          @sourced_fields = sourced_fields
+          @field_path_resolver = field_path_resolver
+        end
+
+        # Resolves the `object_type`, `resolved_relationship`, and `sourced_fields` into an `UpdateTarget`, validating
+        # that everything is defined correctly.
+        #
+        # Returns a tuple of the `update_target` (if valid), and a list of errors.
+        def resolve
+          relationship_errors = validate_relationship
+          data_params, data_params_errors = resolve_data_params
+          routing_value_source, routing_error = resolve_field_source(RoutingSourceAdapter)
+          rollover_timestamp_value_source, rollover_timestamp_error = resolve_field_source(RolloverTimestampSourceAdapter)
+          equivalent_field_errors = resolved_relationship.relationship.validate_equivalent_fields(field_path_resolver)
+
+          all_errors = relationship_errors + data_params_errors + equivalent_field_errors + [routing_error, rollover_timestamp_error].compact
+
+          if all_errors.empty?
+            update_target = UpdateTargetFactory.new_normal_indexing_update_target(
+              type: object_type.name,
+              relationship: resolved_relationship.relationship_name,
+              id_source: resolved_relationship.relation_metadata.foreign_key,
+              data_params: data_params,
+              routing_value_source: routing_value_source,
+              rollover_timestamp_value_source: rollover_timestamp_value_source
+            )
+          end
+
+          [update_target, all_errors]
+        end
+
+        private
+
+        # @dynamic object_type, resolved_relationship, sourced_fields, field_path_resolver
+        attr_reader :object_type, :resolved_relationship, :sourced_fields, :field_path_resolver
+
+        # Applies additional validations (beyond what `RelationshipResolver` applies) on relationships that are
+        # used by `sourced_from` fields.
+        def validate_relationship
+          errors = [] # : ::Array[::String]
+
+          if resolved_relationship.relationship.many?
+            errors << "#{relationship_error_prefix} is a `relates_to_many` relationship, but `sourced_from` is only supported on a `relates_to_one` relationship."
+          end
+
+          relation_metadata = resolved_relationship.relationship_field.runtime_metadata_graphql_field.relation # : SchemaArtifacts::RuntimeMetadata::Relation
+          if relation_metadata.direction == :out
+            errors << "#{relationship_error_prefix} has an outbound foreign key (`dir: :out`), but `sourced_from` is only supported via inbound foreign key (`dir: :in`) relationships."
+          end
+
+          unless relation_metadata.additional_filter.empty?
+            errors << "#{relationship_error_prefix} is a `relationship` using an `additional_filter` but `sourced_from` is not supported on relationships with `additional_filter`."
+          end
+
+          errors
+        end
+
+        # Helper method for building the prefix of relationship-related error messages.
+        def relationship_error_prefix
+          sourced_fields_description = "(referenced from `sourced_from` on field(s): #{sourced_fields.map { |f| "`#{f.name}`" }.join(", ")})"
+          "`#{object_type.name}.#{resolved_relationship.relationship_name}` #{sourced_fields_description}"
+        end
+
+        # Resolves the `sourced_fields` into a data params map, validating them along the way.
+        #
+        # Returns a tuple of the data params and a list of any errors that occurred during resolution.
+        def resolve_data_params
+          related_type = resolved_relationship.related_type
+          errors = [] # : ::Array[::String]
+
+          data_params = sourced_fields.filter_map do |field|
+            field_source = field.source # : SchemaElements::FieldSource
+
+            referenced_field_path = field_path_resolver.resolve_public_path(related_type, field_source.field_path) do |parent_field|
+              !parent_field.type.list?
+            end
+
+            if referenced_field_path.nil?
+              explanation =
+                if field_source.field_path.include?(".")
+                  "could not be resolved: some parts do not exist on their respective types as non-list fields"
+                else
+                  "does not exist as an indexing field"
+                end
+
+              errors << "`#{object_type.name}.#{field.name}` has an invalid `sourced_from` argument: `#{related_type.name}.#{field_source.field_path}` #{explanation}."
+              nil
+            elsif referenced_field_path.type.unwrap_non_null != field.type.unwrap_non_null
+              errors << "The type of `#{object_type.name}.#{field.name}` is `#{field.type}`, but the type of it's source (`#{related_type.name}.#{field_source.field_path}`) is `#{referenced_field_path.type}`. These must agree to use `sourced_from`."
+              nil
+            elsif field.type.non_null?
+              errors << "The type of `#{object_type.name}.#{field.name}` (`#{field.type}`) is not nullable, but this is not allowed for `sourced_from` fields since the value will be `null` before the related type's event is ingested."
+              nil
+            else
+              param = SchemaArtifacts::RuntimeMetadata::DynamicParam.new(
+                source_path: referenced_field_path.path_in_index,
+                cardinality: :one
+              )
+
+              [field.name_in_index, param]
+            end
+          end.to_h
+
+          [data_params, errors]
+        end
+
+        # Helper method that assists with resolving `routing_value_source` and `rollover_timestamp_value_source`.
+        # Uses an `adapter` for the differences in these two cases.
+        #
+        # Returns a tuple of the resolved source (if successful) and an error (if invalid).
+        def resolve_field_source(adapter)
+          # For now we only support one index (so we can use the first index) but someday we may need to support multiple.
+          index = object_type.indices.first # : Index
+
+          field_source_graphql_path_string = adapter.get_field_source(resolved_relationship.relationship, index) do |local_need|
+            relationship_name = resolved_relationship.relationship_name
+
+            error = "Cannot update `#{object_type.name}` documents with data from related `#{relationship_name}` events, " \
+              "because #{adapter.cannot_update_reason(object_type, relationship_name)}. To fix it, add a call like this to the " \
+              "`#{object_type.name}.#{relationship_name}` relationship definition: `rel.equivalent_field " \
+              "\"[#{resolved_relationship.related_type.name} field]\", locally_named: \"#{local_need}\"`."
+
+            return [nil, error]
+          end
+
+          if field_source_graphql_path_string
+            field_path = field_path_resolver.resolve_public_path(resolved_relationship.related_type, field_source_graphql_path_string) do |parent_field|
+              !parent_field.type.list?
+            end
+
+            [field_path&.path_in_index, nil]
+          else
+            [nil, nil]
+          end
+        end
+
+        # Adapter for the `routing_value_source` case for use by `resolve_field_source`.
+        #
+        # @private
+        module RoutingSourceAdapter
+          def self.get_field_source(relationship, index, &block)
+            relationship.routing_value_source_for_index(index, &block)
+          end
+
+          def self.cannot_update_reason(object_type, relationship_name)
+            "`#{object_type.name}` uses custom shard routing but we don't know what `#{relationship_name}` field to use " \
+            "to route the `#{object_type.name}` update requests"
+          end
+        end
+
+        # Adapter for the `rollover_timestamp_value_source` case for use by `resolve_field_source`.
+        #
+        # @private
+        module RolloverTimestampSourceAdapter
+          def self.get_field_source(relationship, index, &block)
+            relationship.rollover_timestamp_value_source_for_index(index, &block)
+          end
+
+          def self.cannot_update_reason(object_type, relationship_name)
+            "`#{object_type.name}` uses a rollover index but we don't know what `#{relationship_name}` timestamp field to use " \
+            "to select an index for the `#{object_type.name}` update requests"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/elastic_graph/schema_definition/json_schema_pruner.rb

@@ -0,0 +1,61 @@
+# 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/constants"
+
+module ElasticGraph
+  module SchemaDefinition
+    # Prunes unused type definitions from a given JSON schema.
+    #
+    # @private
+    class JSONSchemaPruner
+      def self.prune(original_json_schema)
+        initial_type_names = [EVENT_ENVELOPE_JSON_SCHEMA_NAME] + original_json_schema
+          .dig("$defs", EVENT_ENVELOPE_JSON_SCHEMA_NAME, "properties", "type", "enum")
+
+        types_to_keep = referenced_type_names(initial_type_names, original_json_schema["$defs"])
+
+        # The .select will preserve the sort order of the original hash
+        pruned_defs = original_json_schema["$defs"].select { |k, _v| types_to_keep.include?(k) }
+
+        original_json_schema.merge("$defs" => pruned_defs)
+      end
+
+      # Returns a list of type names indicating all types referenced from any type in source_type_names.
+      private_class_method
+      def self.referenced_type_names(source_type_names, original_defs)
+        return Set.new if source_type_names.empty?
+
+        referenced_type_defs = original_defs.select { |k, _| source_type_names.include?(k) }
+        ref_names = collect_ref_names(referenced_type_defs)
+
+        referenced_type_names(ref_names, original_defs) + source_type_names
+      end
+
+      private_class_method
+      def self.collect_ref_names(hash)
+        hash.flat_map do |key, value|
+          case value
+          when ::Hash
+            collect_ref_names(value)
+          when ::Array
+            value.grep(::Hash).flat_map { |subhash| collect_ref_names(subhash) }
+          when ::String
+            if key == "$ref" && (type = value[%r{\A#/\$defs/(.+)\z}, 1])
+              [type]
+            else
+              []
+            end
+          else
+            []
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,31 @@
+# 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
+    # Namespace for modules that are used as mixins. Mixins are used to offer a consistent API for
+    # schema definition features that apply to multiple types of schema elements.
+    module Mixins
+      # Used to indicate if a type only exists in the GraphQL schema (e.g. it has no indexing component).
+      module CanBeGraphQLOnly
+        # Sets whether or not this type only exists in the GraphQL schema
+        #
+        # @param value [Boolean] whether or not this type only exists in the GraphQL schema
+        # @return [void]
+        def graphql_only(value)
+          @graphql_only = value
+        end
+
+        # @return [Boolean] whether or not this type only exists in the GraphQL schema
+        def graphql_only?
+          !!@graphql_only
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,119 @@
+# 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 Mixins
+      # Mixin that supports the customization of derived GraphQL types.
+      #
+      # For each type you define, ElasticGraph generates a number of derived GraphQL types that are needed to facilitate the ElasticGraph
+      # Query API. Methods in this module can be used to customize those derived GraphQL types.
+      module HasDerivedGraphQLTypeCustomizations
+        # Registers a customization block for the named derived graphql types. The provided block will get run on the named derived GraphQL
+        # types, allowing them to be customized.
+        #
+        # @param type_names [Array<String, :all>] names of the derived types to customize, or `:all` to customize all derived types
+        # @return [void]
+        #
+        # @example Customize named derived GraphQL types
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID!"
+        #       t.index "campaigns"
+        #
+        #       t.customize_derived_types "CampaignFilterInput", "CampaignSortOrderInput" do |dt|
+        #         # Add a `@deprecated` directive to two specific derived types.
+        #         dt.directive "deprecated"
+        #       end
+        #     end
+        #   end
+        #
+        # @example Customize all derived GraphQL types
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID!"
+        #       t.index "campaigns"
+        #
+        #       t.customize_derived_types :all do |dt|
+        #         # Add a `@deprecated` directive to all derived types.
+        #         dt.directive "deprecated"
+        #       end
+        #     end
+        #   end
+        def customize_derived_types(*type_names, &customization_block)
+          if type_names.include?(:all)
+            derived_type_customizations_for_all_types << customization_block
+          else
+            type_names.each do |t|
+              derived_type_customizations_by_name[t.to_s] << customization_block
+            end
+          end
+        end
+
+        # Registers a customization block for the named fields on the named derived GraphQL type. The provided block will get run on the
+        # named fields of the named derived GraphQL type, allowing them to be customized.
+        #
+        # @param type_name [String] name of the derived type containing fields you want to customize
+        # @param field_names [Array<String>] names of the fields on the derived types that you wish to customize
+        # @return [void]
+        #
+        # @example Customize named fields of a derived GraphQL type
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID!"
+        #       t.index "campaigns"
+        #
+        #       t.customize_derived_type_fields "CampaignConnection", "pageInfo", "totalEdgeCount" do |dt|
+        #         # Add a `@deprecated` directive to `CampaignConnection.pageInfo` and `CampaignConnection.totalEdgeCount`.
+        #         dt.directive "deprecated"
+        #       end
+        #     end
+        #   end
+        def customize_derived_type_fields(type_name, *field_names, &customization_block)
+          customizations_by_field = derived_field_customizations_by_type_and_field_name[type_name]
+
+          field_names.each do |field_name|
+            customizations_by_field[field_name] << customization_block
+          end
+        end
+
+        # @private
+        def derived_type_customizations_for_type(type)
+          derived_type_customizations_by_name[type.name] + derived_type_customizations_for_all_types
+        end
+
+        # @private
+        def derived_field_customizations_by_name_for_type(type)
+          derived_field_customizations_by_type_and_field_name[type.name]
+        end
+
+        # @private
+        def derived_type_customizations_by_name
+          @derived_type_customizations_by_name ||= ::Hash.new do |hash, type_name|
+            hash[type_name] = []
+          end
+        end
+
+        # @private
+        def derived_field_customizations_by_type_and_field_name
+          @derived_field_customizations_by_type_and_field_name ||= ::Hash.new do |outer_hash, type|
+            outer_hash[type] = ::Hash.new do |inner_hash, field_name|
+              inner_hash[field_name] = []
+            end
+          end
+        end
+
+        private
+
+        def derived_type_customizations_for_all_types
+          @derived_type_customizations_for_all_types ||= []
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+# 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 Mixins
+      # Provides support for annotating any schema element with a GraphQL directive.
+      module HasDirectives
+        # Adds a GraphQL directive to the current schema element.
+        #
+        # @note If you’re using a custom directive rather than a standard GraphQL directive like `@deprecated`, you’ll also need to use
+        #   {API#raw_sdl} to define the custom directive.
+        #
+        # @param name [String] name of the directive
+        # @param arguments [Hash<String, Object>] arguments for the directive
+        # @return [void]
+        #
+        # @example Add a standard GraphQL directive to a field
+        #   ElasticGraph.define_schema do |schema|
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID" do |f|
+        #         f.directive "deprecated"
+        #       end
+        #     end
+        #   end
+        #
+        # @example Define a custom GraphQL directive and add it to an object type
+        #   ElasticGraph.define_schema do |schema|
+        #     # Define a directive we can use to annotate what system a data type comes from.
+        #     schema.raw_sdl "directive @sourcedFrom(system: String!) on OBJECT"
+        #
+        #     schema.object_type "Campaign" do |t|
+        #       t.field "id", "ID"
+        #       t.directive "sourcedFrom", system: "campaigns"
+        #     end
+        #   end
+        def directive(name, arguments = {})
+          directives << schema_def_state.factory.new_directive(name, arguments)
+        end
+
+        # Helper method designed for use by including classes to get the formatted directive SDL.
+        #
+        # @param suffix_with [String] suffix to add on the end of the SDL
+        # @param prefix_with [String] prefix to add to the beginning of the SDL
+        # @return [String] SDL string for the directives
+        # @api private
+        def directives_sdl(suffix_with: "", prefix_with: "")
+          sdl = directives.map(&:to_sdl).join(" ")
+          return sdl if sdl.empty?
+          prefix_with + sdl + suffix_with
+        end
+
+        # @return [Array<SchemaElements::Directive>] directives attached to this schema element
+        def directives
+          @directives ||= []
+        end
+      end
+    end
+  end
+end