anyway_config 2.8.1 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2505731c8729ea6a097cef8718c441684124da047a6856bd6156b4592c1ad9b
-  data.tar.gz: d20b15281220f9c3d77b7440ffcf915db6b28e6c7555ecec5ac9e4583de34887
+  metadata.gz: 910bf1014d5b1b2a7952b2e6da131a341722998f3b891d096f4d5764006fac23
+  data.tar.gz: 6f9233771e022ccb6d3ea3d03ee2b15bee8e2e3d322aa3434cd5d08b8794cf14
 SHA512:
-  metadata.gz: 70db78ae8a9859a4f660173101127d4e8d30c6a059f5b3cba121864be120a787a5998f740a948651f84c82cb22e87f7bce7926a4ad6b27352297dbc9f24d20b4
-  data.tar.gz: a314943f0a1fe0779235a75656d80cbf7a1525bbd6db24ab4fe15f508d4ac3c2790819a6d9abf39682c17c0bb0fadf4184976e9a9753dc3d61f594b910bd211a
+  metadata.gz: 11f0d4f61ebabda431abba36837438c767405a0432e2f8f8ae1d2460b35e8e14438b9ed2acb6cb9d2d1b6889111e61cfecdf7abed2e2d4bc40eccba416c1d6f5
+  data.tar.gz: 3bf99f8766ed1a38ea3d9b6f114bf59c694c492ecd0f635067b97750750c2afea3e4d3c476e4d7bfa70c6e02fb478e36f273a4b32613712c79e10dc7c9fed400

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 ## master
 
+## 2.9.0 (2026-10-20)
+
+- Add a new `enforce_config_schema` to warn or raise on unknown attributes. ([@palkan][])
+
+  When the schema is enforced, the config attributes defined in the key-based sources (YAML, credentials, etc.) must correspond to `attr_config` names in the corresponding class. Providing an unknown attribute (e.g., a typo) would raise or print a warning depending on the parameter value:
+
+```ruby
+Anyway::Settings.enforce_config_schema = true # or :warn
+
+# in Rails
+config.anyway_config.enforce_config_schema = true
+```
+
+- EJSON loader now ignores underscore-prefixed (unencrypted) keys. ([@palkan][])
+
 ## 2.8.1 (2026-07-22)
 
 - Fix default loaders order to keep ENV the last one (=higher precedence). ([@palkan][])

data/README.md

@@ -22,8 +22,9 @@ For application developers, Anyway Config could be useful to:
 **NOTE:** this readme shows documentation for 2.x version.
 For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_config/tree/1-4-stable).
 
-<a href="https://evilmartians.com/?utm_source=anyway_config">
-<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
+<br/>
+
+<img src="https://cdn.evilmartians.com/badges/logo-no-label.svg" alt="Evil Martians logo" width="22" height="16" /> <b>Anyway Config</b> is built by <b><a href="https://evilmartians.com/">Evil Martians</a></b>, an American design and engineering consultancy for <b>developer tools, AI, and cybersecurity startups</b>.
 
 ## Links
 
@@ -37,6 +38,7 @@ For version 1.x see the [1-4-stable branch](https://github.com/palkan/anyway_con
   - [Configuration classes](#configuration-classes)
   - [Dynamic configuration](#dynamic-configuration)
   - [Validation & Callbacks](#validation-and-callbacks)
+  - [Enforcing config schema](#enforcing-config-schema)
 - [Using with Rails applications](#using-with-rails)
   - [Data population](#data-population)
   - [Organizing configs](#organizing-configs)
@@ -345,6 +347,45 @@ class MyConfig < Anyway::Config
 end
 ```
 
+### Enforcing config schema
+
+By default, Anyway Config ignores keys that don't match any of the config attributes. Thus, a typo in a YAML file (e.g., `hots` instead of `host`) goes unnoticed. You can make Anyway Config check for unknown attributes via the `enforce_config_schema` setting:
+
+```ruby
+# Raise Anyway::Config::UnknownAttributesError
+Anyway::Settings.enforce_config_schema = true
+
+# Print a warning instead
+Anyway::Settings.enforce_config_schema = :warn
+
+# Or in Rails
+config.anyway_config.enforce_config_schema = true
+```
+
+The schema is only enforced for key-based (_schemaful_) sources: YAML files, Rails credentials and secrets, and EJSON. Environment-based sources (ENV, Doppler) are never checked, since env prefixes can easily collide with unrelated variables (e.g., `AWS_PROFILE` for the `aws` config).
+
+Only top-level keys are checked; nested hashes are not validated.
+
+#### Allowing unknown attributes for some configs
+
+You can use the `rescue_unknown_attributes_with` configuration parameter to ignore specific attributes. It's called for every unknown attribute with the config object and the attribute name; return a truthy value to skip (allow) it:
+
+```ruby
+Anyway::Settings.rescue_unknown_attributes_with = ->(config, key) do
+  config.config_name == "app"
+end
+```
+
+This is particularly useful when you have multiple config classes associated with the same configurable entity (say, a service provider).
+
+#### Unknown explicit values
+
+Unknown attributes passed explicitly (`MyConfig.new(hots: "localhost")`) will raise disregards the `enforce_config_schema` setting in the future. Currently, they follow the `enforce_config_schema` configuration but we recommend to opt-in for the stricter future behaviour:
+
+```ruby
+Anyway::Settings.future.use :reject_unknown_overrides
+```
+
 ## Using with Rails
 
 **NOTE:** version 2.x supports Rails >= 6.0; for older versions use version 1.x of the gem.
@@ -825,6 +866,8 @@ class MyConfig < Anyway::Config
 end
 ```
 
+Underscore-prefixed keys (which are not encrypted by EJSON, e.g., `_public_key`) are ignored.
+
 **NOTE:** You can opt-out from EJSON loader by specifying the `ANYWAY_CONFIG_DISABLE_EJSON=true` env var (in case you have the `ejson` executable in your PATH, but don't want to use it with Anyway Config).
 
 ### Custom loaders
@@ -865,6 +908,9 @@ class ChamberConfigLoader < Base
     warn "Couldn't decrypt Chamber settings: #{e.message}"
     {}
   end
+
+  # Report unknown keys if enforce_config_schema is enabled
+  def schemaful? = true
 end
 
 # Don't forget to register it

data/lib/.rbnext/2.7/anyway/loaders/yaml.rb

@@ -28,6 +28,8 @@ module Anyway
         Utils.deep_merge!(base_config, local_config)
       end
 
+      def schemaful?() ;  true; end
+
       private
 
       def environmental?(parsed_yml)

data/lib/.rbnext/2.7/anyway/settings.rb

@@ -38,6 +38,7 @@ module Anyway
       end
 
       setting :unwrap_known_environments, true
+      setting :reject_unknown_overrides, true
 
       private
 
@@ -55,6 +56,14 @@ module Anyway
       # Suppress required validations for CI/CD pipelines
       attr_accessor :suppress_required_validations
 
+      # Whether to check for unknown attributes in schemaful (key-based) sources:
+      # false — ignore unknown attributes, true — raise, :warn — print a warning
+      attr_accessor :enforce_config_schema
+
+      # A callable (config, key) -> bool to ignore specific unknown attributes
+      # (e.g., when the same source is shared by multiple configs)
+      attr_accessor :rescue_unknown_attributes_with
+
       # A proc returning a path to YML config file given the config name
       attr_reader :default_config_path
 
@@ -113,5 +122,8 @@ module Anyway
 
     # By default, use ANYWAY_SUPPRESS_VALIDATIONS
     self.suppress_required_validations = %w[1 t true y yes].include?(ENV["ANYWAY_SUPPRESS_VALIDATIONS"])
+
+    # Unknown attributes are ignored by default
+    self.enforce_config_schema = false
   end
 end

data/lib/.rbnext/3.0/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -467,6 +478,43 @@ module Anyway # :nodoc:
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/.rbnext/3.0/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **__kwrest__)
         @local = local
       end
 
       def use_local?() ;  @local == true; end
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() ;  false; end
     end
   end
 end

data/lib/.rbnext/3.0/anyway/loaders/ejson.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "anyway/ejson_parser"
+
+module Anyway
+  module Loaders
+    class EJSON < Base
+      class << self
+        attr_accessor :bin_path
+      end
+
+      self.bin_path = "ejson"
+
+      def call(name:, ejson_namespace: name, ejson_parser: Anyway::EJSONParser.new(EJSON.bin_path), **_options)
+        configs = []
+
+        rel_config_paths.each do |rel_config_path|
+          secrets_hash, rel_path =
+            extract_hash_from_rel_config_path(
+              ejson_parser: ejson_parser,
+              rel_config_path: rel_config_path
+            )
+
+          next unless secrets_hash
+
+          config_hash = if ejson_namespace
+            secrets_hash[ejson_namespace]
+          else
+            secrets_hash
+          end
+
+          next unless config_hash.is_a?(Hash)
+
+          # Underscore-prefixed keys are not encrypted (e.g., _public_key)
+          config_hash = config_hash.reject { |key, _| key.start_with?("_") }
+
+          configs <<
+            trace!(:ejson, path: rel_path) do
+              config_hash
+            end
+        end
+
+        return {} if configs.empty?
+
+        configs.inject do |result_config, next_config|
+          Utils.deep_merge!(result_config, next_config)
+        end
+      end
+
+      def schemaful?() ;  true; end
+
+      private
+
+      def rel_config_paths
+        chain = [environmental_rel_config_path]
+
+        chain << "secrets.local.ejson" if use_local?
+
+        chain
+      end
+
+      def environmental_rel_config_path
+        if Settings.current_environment
+          # if environment file is absent, then take data from the default one
+          [
+            "#{Settings.current_environment}/secrets.ejson",
+            default_rel_config_path
+          ]
+        else
+          default_rel_config_path
+        end
+      end
+
+      def default_rel_config_path
+        "secrets.ejson"
+      end
+
+      def extract_hash_from_rel_config_path(ejson_parser:, rel_config_path:)
+        rel_config_path = [rel_config_path] unless rel_config_path.is_a?(Array)
+
+        rel_config_path.each do |rel_conf_path|
+          rel_path = "config/#{rel_conf_path}"
+          abs_path = "#{Settings.app_root}/#{rel_path}"
+
+          result = ejson_parser.call(abs_path)
+
+          return [result, rel_path] if result
+        end
+
+        nil
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/anyway/loaders/yaml.rb

@@ -28,6 +28,8 @@ module Anyway
         Utils.deep_merge!(base_config, local_config)
       end
 
+      def schemaful?() ;  true; end
+
       private
 
       def environmental?(parsed_yml)

data/lib/.rbnext/3.0/anyway/rails/loaders/credentials.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Anyway
+  module Rails
+    module Loaders
+      class Credentials < Anyway::Loaders::Base
+        LOCAL_CONTENT_PATH = "config/credentials/local.yml.enc"
+
+        def call(name:, **_options)
+          return {} unless ::Rails.application.respond_to?(:credentials)
+
+          # do not load from credentials if we're in the context
+          # of the `credentials:edit` command
+          return {} if defined?(::Rails::Command::CredentialsCommand)
+
+          # Create a new hash cause credentials are mutable!
+          config = {}
+
+          trace!(
+            :credentials,
+            store: credentials_path
+          ) do
+            ::Rails.application.credentials.config[name.to_sym]
+          end.then do |creds|
+            Utils.deep_merge!(config, creds) if creds
+          end
+
+          if use_local?
+            trace!(:credentials, store: LOCAL_CONTENT_PATH) do
+              local_credentials(name)
+            end.then { |creds| Utils.deep_merge!(config, creds) if creds }
+          end
+
+          config
+        end
+
+        def schemaful?() ;  true; end
+
+        private
+
+        def local_credentials(name)
+          local_creds_path = ::Rails.root.join(LOCAL_CONTENT_PATH).to_s
+
+          return unless File.file?(local_creds_path)
+
+          creds = ::Rails.application.encrypted(
+            local_creds_path,
+            key_path: ::Rails.root.join("config/credentials/local.key")
+          )
+
+          creds.config[name.to_sym]
+        end
+
+        def credentials_path
+          if ::Rails.application.config.respond_to?(:credentials)
+            ::Rails.root.join(::Rails.application.config.credentials.content_path).relative_path_from(::Rails.root).to_s
+          else
+            "config/credentials.yml.enc"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.0/anyway/rails/loaders/secrets.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Anyway
+  module Rails
+    module Loaders
+      class Secrets < Anyway::Loaders::Base
+        def call(name:, **_options)
+          return {} unless ::Rails.application.respond_to?(:secrets)
+
+          # Create a new hash cause secrets are mutable!
+          config = {}
+
+          trace!(:secrets) do
+            secrets.public_send(name)
+          end.then do |secrets|
+            Utils.deep_merge!(config, secrets) if secrets
+          end
+
+          config
+        end
+
+        def schemaful?() ;  true; end
+
+        private
+
+        def secrets
+          @secrets ||= ::Rails.application.secrets.tap do |_|
+            # Reset secrets state if the app hasn't been initialized
+            # See https://github.com/palkan/anyway_config/issues/14
+            next if ::Rails.application.initialized?
+
+            # Address unable to load application: NameError: instance variable @secrets
+            # not defined
+            next unless ::Rails.application.instance_variable_defined?(:@secrets)
+
+            ::Rails.application.remove_instance_variable(:@secrets)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/.rbnext/3.1/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -467,6 +478,43 @@ module Anyway # :nodoc:
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/.rbnext/3.1/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **__kwrest__)
         @local = local
       end
 
       def use_local?() = @local == true
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() = false
     end
   end
 end

data/lib/.rbnext/3.2/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -467,6 +478,43 @@ module Anyway # :nodoc:
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/.rbnext/3.2/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **__kwrest__)
         @local = local
       end
 
       def use_local?() = @local == true
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() = false
     end
   end
 end

data/lib/.rbnext/3.4/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -467,6 +478,43 @@ module Anyway # :nodoc:
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { |it| rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { |it| format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/anyway/config.rb

@@ -33,6 +33,7 @@ module Anyway # :nodoc:
       deconstruct_keys
       dig
       dup
+      format_unknown_attribute
       initialize
       load
       load_from_sources
@@ -52,6 +53,8 @@ module Anyway # :nodoc:
 
     class ValidationError < Error; end
 
+    class UnknownAttributesError < ValidationError; end
+
     include OptparseConfig
     include DynamicConfig
 
@@ -374,6 +377,8 @@ module Anyway # :nodoc:
         )
 
         if overrides
+          reject_unknown_config_attributes!(overrides, source: :overrides, strict: Settings.future.reject_unknown_overrides == true)
+
           Tracing.trace!(:load) { overrides }
 
           Utils.deep_merge!(base_config, overrides)
@@ -400,10 +405,16 @@ module Anyway # :nodoc:
     def load_from_sources(base_config, **opts)
       source_filter = self.class.configuration_sources
 
-      Anyway.loaders.each do |(id, loader)|
+      Anyway.loaders.each do |(id, loader_or_proc)|
         next if source_filter && !source_filter.include?(id)
-        Utils.deep_merge!(base_config, loader.call(**opts))
+
+        loader = (loader_or_proc.is_a?(Class) && loader_or_proc <= Loaders::Base) ? loader_or_proc.new(**opts) : loader_or_proc
+        loader_data = loader.call(**opts)
+        reject_unknown_config_attributes!(loader_data, source: id) if loader.is_a?(Loaders::Base) && loader.schemaful?
+
+        Utils.deep_merge!(base_config, loader_data)
       end
+
       base_config
     end
 
@@ -467,6 +478,43 @@ module Anyway # :nodoc:
       end
     end
 
+    def reject_unknown_config_attributes!(data, source:, strict: false)
+      return if data.nil? || data.empty?
+
+      mode = strict || Settings.enforce_config_schema
+      return unless mode
+
+      known = self.class.config_attributes.map(&:to_s)
+      unknown = data.keys.map(&:to_s) - known
+
+      unless strict
+        rescuer = Settings.rescue_unknown_attributes_with
+        unknown.reject! { rescuer.call(self, it) } if rescuer
+      end
+
+      return if unknown.empty?
+
+      msg = "Unknown config attributes for `#{self.class.name || "<anonymous>"}(config_name: #{config_name})` " \
+        "provided by #{source}: #{unknown.map { format_unknown_attribute(it, known) }.join(", ")}"
+
+      if strict
+        raise ArgumentError, msg
+      elsif mode == :warn
+        Kernel.warn msg
+      else
+        raise UnknownAttributesError, msg
+      end
+    end
+
+    def format_unknown_attribute(key, known)
+      return key unless defined?(::DidYouMean::SpellChecker)
+
+      suggestions = ::DidYouMean::SpellChecker.new(dictionary: known).correct(key)
+      return key if suggestions.empty?
+
+      "#{key} (did you mean: #{suggestions.join(", ")}?)"
+    end
+
     def write_config_attr(key, val)
       key = key.to_sym
       return unless self.class.config_attributes.include?(key)

data/lib/anyway/loaders/base.rb

@@ -11,11 +11,15 @@ module Anyway
         end
       end
 
-      def initialize(local:)
+      def initialize(local: Anyway::Settings.use_local_files, **)
         @local = local
       end
 
       def use_local?() = @local == true
+
+      # Whether this loader supports strict schema (so we can warn or raise on
+      # unknown attributes)
+      def schemaful?() = false
     end
   end
 end

data/lib/anyway/loaders/ejson.rb

@@ -26,11 +26,14 @@ module Anyway
           config_hash = if ejson_namespace
             secrets_hash[ejson_namespace]
           else
-            secrets_hash.except("_public_key")
+            secrets_hash
           end
 
           next unless config_hash.is_a?(Hash)
 
+          # Underscore-prefixed keys are not encrypted (e.g., _public_key)
+          config_hash = config_hash.reject { |key, _| key.start_with?("_") }
+
           configs <<
             trace!(:ejson, path: rel_path) do
               config_hash
@@ -44,6 +47,8 @@ module Anyway
         end
       end
 
+      def schemaful?() = true
+
       private
 
       def rel_config_paths

data/lib/anyway/loaders/yaml.rb

@@ -28,6 +28,8 @@ module Anyway
         Utils.deep_merge!(base_config, local_config)
       end
 
+      def schemaful?() = true
+
       private
 
       def environmental?(parsed_yml)

data/lib/anyway/rails/loaders/credentials.rb

@@ -34,6 +34,8 @@ module Anyway
           config
         end
 
+        def schemaful?() = true
+
         private
 
         def local_credentials(name)

data/lib/anyway/rails/loaders/secrets.rb

@@ -19,6 +19,8 @@ module Anyway
           config
         end
 
+        def schemaful?() = true
+
         private
 
         def secrets

data/lib/anyway/rails.rb

@@ -12,7 +12,7 @@ require "anyway/rails/loaders"
 # Configure Rails loaders
 Anyway.loaders.override :yml, Anyway::Rails::Loaders::YAML
 
-if Rails::VERSION::MAJOR >= 7 && Rails::VERSION::MINOR >= 1
+if Gem::Version.new(Rails.version) >= Gem::Version.new("7.1")
   Anyway.loaders.insert_after :yml, :credentials, Anyway::Rails::Loaders::Credentials
 else
   Anyway.loaders.insert_after :yml, :secrets, Anyway::Rails::Loaders::Secrets

data/lib/anyway/settings.rb

@@ -38,6 +38,7 @@ module Anyway
       end
 
       setting :unwrap_known_environments, true
+      setting :reject_unknown_overrides, true
 
       private
 
@@ -55,6 +56,14 @@ module Anyway
       # Suppress required validations for CI/CD pipelines
       attr_accessor :suppress_required_validations
 
+      # Whether to check for unknown attributes in schemaful (key-based) sources:
+      # false — ignore unknown attributes, true — raise, :warn — print a warning
+      attr_accessor :enforce_config_schema
+
+      # A callable (config, key) -> bool to ignore specific unknown attributes
+      # (e.g., when the same source is shared by multiple configs)
+      attr_accessor :rescue_unknown_attributes_with
+
       # A proc returning a path to YML config file given the config name
       attr_reader :default_config_path
 
@@ -113,5 +122,8 @@ module Anyway
 
     # By default, use ANYWAY_SUPPRESS_VALIDATIONS
     self.suppress_required_validations = %w[1 t true y yes].include?(ENV["ANYWAY_SUPPRESS_VALIDATIONS"])
+
+    # Unknown attributes are ignored by default
+    self.enforce_config_schema = false
   end
 end

data/lib/anyway/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Anyway # :nodoc:
-  VERSION = "2.8.1"
+  VERSION = "2.9.0"
 end

data/sig/anyway_config.rbs

@@ -9,6 +9,10 @@ module Anyway
     def self.default_environmental_key: -> String?
     def self.suppress_required_validations: -> bool
     def self.known_environments: -> Array[String]?
+    def self.enforce_config_schema: -> (bool | :warn)
+    def self.enforce_config_schema=: (bool | :warn) -> void
+    def self.rescue_unknown_attributes_with: -> (^(Config, String) -> boolish)?
+    def self.rescue_unknown_attributes_with=: ((^(Config, String) -> boolish)?) -> void
 
     class Future
       def self.setting: (untyped name, untyped default_value) -> untyped
@@ -107,6 +111,8 @@ module Anyway
     private
     attr_reader values: Hash[untyped, untyped]
     def raise_validation_error: (String msg) -> void
+    def reject_unknown_config_attributes!: (Hash[untyped, untyped]? data, source: Symbol, ?strict: bool) -> void
+    def format_unknown_attribute: (String key, Array[String] known) -> String
     def flatten_hash: (Hash[untyped, untyped], String, Hash[String, String]) -> Hash[String, String]
 
     class Error < StandardError
@@ -114,6 +120,9 @@ module Anyway
 
     class ValidationError < Error
     end
+
+    class UnknownAttributesError < ValidationError
+    end
   end
 
   class Env
@@ -127,8 +136,10 @@ module Anyway
       include Tracing
 
       def self.call: (?local: bool, **untyped) -> untyped
-      def initialize: (local: bool) -> void
+      def initialize: (?local: bool, **untyped) -> void
+      def call: (name: String, env_prefix: String, config_path: String | Pathname, **untyped) -> Hash[untyped, untyped]
       def use_local?: -> bool
+      def schemaful?: -> bool
     end
 
     interface _Loader

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: anyway_config
 version: !ruby/object:Gem::Version
-  version: 2.8.1
+  version: 2.9.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby-next-core
@@ -130,7 +130,10 @@ files:
 - lib/.rbnext/3.0/anyway/config.rb
 - lib/.rbnext/3.0/anyway/loaders.rb
 - lib/.rbnext/3.0/anyway/loaders/base.rb
+- lib/.rbnext/3.0/anyway/loaders/ejson.rb
 - lib/.rbnext/3.0/anyway/loaders/yaml.rb
+- lib/.rbnext/3.0/anyway/rails/loaders/credentials.rb
+- lib/.rbnext/3.0/anyway/rails/loaders/secrets.rb
 - lib/.rbnext/3.0/anyway/tracing.rb
 - lib/.rbnext/3.1/anyway/config.rb
 - lib/.rbnext/3.1/anyway/dynamic_config.rb