schema-model 0.8.0 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f672bab800b79f5e9a8b390268466caaf7a42822b0b0632f023f6539fbae48aa
-  data.tar.gz: 5486532778b3a246d66c0c2350586fd77ebf9955ef311a719c5053d656afe0be
+  metadata.gz: 1a95ca01d369cc20699a43f7a13b46fe567768c6ba5b8281cfb12800c56324e0
+  data.tar.gz: c185ad7251b43193473da560d837bd4f87fc00558c540e635fa6618a8719773f
 SHA512:
-  metadata.gz: ca482dfd23e73cea044bf572e819864415ee68768cdb0b98a756e92fbb06c2d800b7cdd6c2afde4d5c77559d226a7e3cf681f4043a17b118c17ed24fee0cdb9c
-  data.tar.gz: f555174a32c7adbe3b713bb726038f325168f07820d6309479be0715af91bb5e684d73d51466a0f71cc806ecd7ca98f2006bf8820008c126ee4f25f220ffdcde
+  metadata.gz: e0e993ff5247dcb1acd76acbecaa2f0b65fcdf30e94d4342c8f362bc2ce0c87edf8ca2c511e35cf791a9150be29ff3f6f633f0b8d815ed7c3ae08dfff71d50f5
+  data.tar.gz: 34c05bb3bb1399be9c9d060617ad41cfcf8c2714c094097c5868fd52b56525c3be2e59af5be28ee28a5369e3e254267c389b40b496011ca8213350168c3ea7d6

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## [0.9.1](https://github.com/dougyouch/schema/compare/v0.9.0...v0.9.1) (2026-10-04)
+
+
+### Bug Fixes
+
+* **associations:** keep association defaults out of the set values ([3d90df3](https://github.com/dougyouch/schema/commit/3d90df3f8e8fa0b5da75cb313137d76a49106091))
+
+## [0.9.0](https://github.com/dougyouch/schema/compare/v0.8.0...v0.9.0) (2026-10-04)
+
+
+### Features
+
+* **model:** add set_attribute_values, parsed_and_valid? and full_error_messages ([0c8b922](https://github.com/dougyouch/schema/commit/0c8b922cb4417720b70d069a8c51fb80b3b1c644))
+
+
+### Bug Fixes
+
+* **validator:** fail schema validation on nested parsing errors ([b17704a](https://github.com/dougyouch/schema/commit/b17704af2629d3a4a81ee69f748e216a8c5d7488))
+
 ## [0.8.0](https://github.com/dougyouch/schema/compare/v0.7.4...v0.8.0) (2026-10-04)
 
 

data/README.md

@@ -59,6 +59,128 @@ user.active        # => true (parsed from "yes")
 user.tags          # => ["ruby", "rails", "developer"]
 ```
 
+## Use Cases
+
+### Typed JSON columns on ActiveRecord models
+
+Wrap a JSON/JSONB column in a schema so the record works with typed values, rejects bad data, and writes back clean JSON:
+
+```ruby
+class ConfigSchema
+  include Schema::All
+
+  attribute :api_key, :string
+  attribute :timeout, :integer, default: 30
+  attribute :enabled, :boolean
+
+  has_many :endpoints do
+    attribute :url, :string
+    validates :url, presence: true
+  end
+
+  validates :api_key, presence: true
+  validates :endpoints, schema: true
+end
+
+class Integration < ActiveRecord::Base
+  validate :validate_config, if: :config_updated?
+  before_save :update_data_from_config, if: :config_updated?
+
+  def config=(config_data)
+    @config = ConfigSchema.from_hash(config_data)
+  end
+
+  def config
+    @config ||= ConfigSchema.from_hash(data)
+  end
+
+  # reading config counts as an update, since the caller may change it in place
+  def config_updated?
+    defined?(@config)
+  end
+
+  private
+
+  def update_data_from_config
+    self.data = config.as_json
+  end
+
+  # parsing errors (e.g. timeout: "abc") don't make valid? false, so check both
+  def validate_config
+    return if config.parsed_and_valid?
+
+    config.full_error_messages.each { |message| errors.add(:config, message) }
+  end
+end
+
+integration.config = { 'api_key' => 'abc', 'timeout' => '60', 'endpoints' => [{ 'url' => 'https://example.com' }] }
+integration.config.timeout  # => 60
+integration.save            # writes data as { api_key: "abc", timeout: 60, endpoints: [{ url: "https://example.com" }] }
+```
+
+Use `from_hash`, not `new`, to build a schema from data. `from_hash(nil)` returns an empty model, so a record whose column is still `NULL` works too.
+
+If a single "Config is invalid" error is enough, `validates :config, schema: true, if: :config_updated?` replaces `validate_config`; it fails on parsing errors as well as validation errors.
+
+### Validating API input in controllers
+
+Describe the JSON an endpoint accepts as a schema. Values arrive converted to the right types, unknown keys are reported, and the schema acts as the allowlist, so strong parameters aren't needed:
+
+```ruby
+class CreateUserSchema
+  include Schema::All
+
+  attribute :name, :string
+  attribute :email, :string
+  attribute :age, :integer
+
+  validates :name, :email, presence: true
+end
+
+class UsersController < ApplicationController
+  def create
+    input = CreateUserSchema.from_hash(JSON.parse(request.raw_post))
+    unless input.parsed_and_valid?
+      return render json: { errors: input.full_error_messages }, status: :unprocessable_entity
+    end
+
+    user = User.create!(input.as_json)
+    render json: user, status: :created
+  end
+end
+```
+
+`parsed_and_valid?` runs the validations even when there are parsing errors, so `full_error_messages` reports everything wrong with the input at once, e.g. `["Age is invalid", "Admin is an unknown attribute", "Email can't be blank"]`.
+
+The body is parsed from `request.raw_post` rather than taken from `params`, because Rails adds keys to `params` (`controller`, `action`, and the wrapped parameters key) that the schema would report as unknown attributes.
+
+### PATCH endpoints
+
+`set_attribute_values` returns only the fields that were present in the input, including ones sent as `null`. That separates "not sent" from "sent as null", which is what a PATCH route needs:
+
+```ruby
+class UpdateUserSchema
+  include Schema::All
+
+  attribute :name, :string
+  attribute :email, :string
+  attribute :age, :integer
+end
+
+def update
+  input = UpdateUserSchema.from_hash(JSON.parse(request.raw_post))
+  unless input.parsed_and_valid?
+    return render json: { errors: input.full_error_messages }, status: :unprocessable_entity
+  end
+
+  # body {"name": "Joe", "age": null} => { name: "Joe", age: nil }: updates name, clears age, leaves email alone
+  user.update!(input.set_attribute_values)
+  render json: user
+end
+```
+
+Associations in `set_attribute_values` are schema models; call `as_json` on them if the record expects hashes. For a single attribute, `input.name_was_set?` answers the same question.
+
 ## Data Types
 
 ### Basic Types
@@ -330,9 +452,20 @@ user.parsing_errors.full_messages  # => ["Age is invalid"]
 
 A plain `Schema::Model` uses `Schema::Errors`, which stores the codes themselves (`user.parsing_errors[:age] # => ["invalid"]`).
 
+### Checking Everything at Once
+
+```ruby
+user = UserSchema.from_hash(name: 'John', age: 'not-a-number', email: nil)
+
+user.parsed_and_valid?    # => false; runs validations even though parsing failed
+user.full_error_messages  # => ["Age is invalid", "Email can't be blank"] (parsing messages, then validation messages)
+```
+
+`full_error_messages` reports the last validation run, so call `parsed_and_valid?` (or `valid?`) first.
+
 ### Validating Nested Schemas
 
-`validates ..., schema: true` (`SchemaValidator`) marks the parent invalid when a nested model, or any model in a has-many list, is invalid:
+`validates ..., schema: true` (`SchemaValidator`) marks the parent invalid when a nested model, or any model in a has-many list, has parsing errors or fails its validations:
 
 ```ruby
 class OrderSchema
@@ -408,13 +541,14 @@ user.as_json(reject_filter: ->(name, value, opts) { value.nil? })
 a = ContactSchema.from_hash(name: 'John')
 b = ContactSchema.from_hash('name' => 'John')
 
-a == b               # => true (same class and attribute values, nested models included)
-a.attribute_values   # => { name: "John", email: nil }
-a.inspect            # => #<ContactSchema name: "John"> (only attributes that were set)
+a == b                   # => true (same class and attribute values, nested models included)
+a.attribute_values       # => { name: "John", email: nil }
+a.set_attribute_values   # => { name: "John" } (only fields present in the input)
+a.inspect                # => #<ContactSchema name: "John"> (only attributes that were set)
 
-copy = a.deep_dup    # copies nested models, arrays, hashes, strings and parsing errors
+copy = a.deep_dup        # copies nested models, arrays, hashes, strings and parsing errors
 copy.name << '!'
-a.name               # => "John"
+a.name                   # => "John"
 ```
 
 `dup` is Ruby's shallow copy, so nested models are shared with the original.

data/lib/schema/active_model_validations.rb

@@ -25,6 +25,17 @@ module Schema
       valid_model!
     end
 
+    # runs validations even when there are parsing errors, so full_error_messages has both
+    def parsed_and_valid?
+      valid = valid?
+      valid && parsed?
+    end
+
+    # parsing error messages followed by the messages from the last validation run
+    def full_error_messages
+      parsing_errors.full_messages + errors.full_messages
+    end
+
     # no-doc
     module OverrideParsingErrors
       def parsing_errors

data/lib/schema/attribute_values.rb

@@ -12,6 +12,12 @@ module Schema
       end
     end
 
+    # only the attributes and associations present in the input (including ones set to nil),
+    # e.g. the fields a PATCH request sent
+    def set_attribute_values
+      set_field_options.to_h { |field_options| [field_options[:name], public_send(field_options[:getter])] }
+    end
+
     def ==(other)
       other.instance_of?(self.class) && other.attribute_values == attribute_values
     end

data/lib/schema/deep_copy.rb

@@ -16,13 +16,19 @@ module Schema
       self.class.schema.each_value do |field_options|
         next if field_options[:alias_of]
 
-        ivar = field_options[:instance_variable]
-        next unless source.instance_variable_defined?(ivar)
+        copy_instance_variable_from(source, field_options[:instance_variable])
+        next unless field_options[:association] && field_options[:default]
 
-        instance_variable_set(ivar, ::Schema::Utils.deep_dup_value(source.instance_variable_get(ivar)))
+        copy_instance_variable_from(source, ::Schema::Utils.association_default_instance_variable(field_options))
       end
     end
 
+    def copy_instance_variable_from(source, ivar)
+      return unless source.instance_variable_defined?(ivar)
+
+      instance_variable_set(ivar, ::Schema::Utils.deep_dup_value(source.instance_variable_get(ivar)))
+    end
+
     def copy_parsing_errors_from(source)
       @parsing_errors = nil
       ::Schema::Utils.parsing_error_pairs(source.parsing_errors).each do |attribute, message|

data/lib/schema/utils.rb

@@ -108,7 +108,15 @@ module Schema
       )
     end
 
+    # where an association's default is kept once read, separate from the value set from the input
+    def association_default_instance_variable(options)
+      "#{options[:instance_variable]}_default"
+    end
+
+    # the default is memoized so changes to it stick, but in its own instance variable, so reading
+    # it doesn't make the association count as set (set_attribute_values, not_set?, inspect)
     def add_association_default_methods(kls, options)
+      default_instance_variable = association_default_instance_variable(options)
       kls.class_eval(
         <<-STR, __FILE__, __LINE__ + 1
   def #{options[:default_method]}
@@ -116,7 +124,9 @@ module Schema
   end
 
   def #{options[:getter]}
-    #{options[:instance_variable]} ||= #{options[:default_method]}
+    return #{options[:instance_variable]} unless #{options[:instance_variable]}.nil?
+
+    #{default_instance_variable} ||= #{options[:default_method]}
   end
         STR
       )

data/lib/schema/version.rb

@@ -2,5 +2,5 @@
 
 module Schema
   # Gem version, bumped by release-please
-  VERSION = '0.8.0'
+  VERSION = '0.9.1'
 end

data/lib/schema_validator.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# SchemaValidator validates nested schemas
+# SchemaValidator validates nested schemas: each one must have no parsing errors and pass its validations
 class SchemaValidator < ActiveModel::EachValidator
   def validate_each(record, attribute, value)
     record.errors.add(attribute, options.fetch(:message, :invalid)) unless valid_schema?(value)
@@ -11,12 +11,13 @@ class SchemaValidator < ActiveModel::EachValidator
   def valid_schema?(value)
     return true unless value
 
-    if value.is_a?(Array)
-      value.all? do |schema|
-        !schema || schema.valid?
-      end
-    else
-      value.valid?
-    end
+    schemas = value.is_a?(Array) ? value.compact : [value]
+    # map before all? so every nested schema runs its validations and has its errors filled in
+    schemas.map { |schema| parsed_and_valid?(schema) }.all?
+  end
+
+  def parsed_and_valid?(schema)
+    valid = schema.valid?
+    valid && schema.parsed?
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema-model
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.1
 platform: ruby
 authors:
 - Doug Youch