schema-model 0.9.1 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a95ca01d369cc20699a43f7a13b46fe567768c6ba5b8281cfb12800c56324e0
-  data.tar.gz: c185ad7251b43193473da560d837bd4f87fc00558c540e635fa6618a8719773f
+  metadata.gz: 2f4f7d2224dda7f2a0ced1da41e8597e6374df27a22fd739c1bd86a0b02441c3
+  data.tar.gz: 4ff7d3bcf5f8e80d241d7e85b25c84f0a7f651c1e43beeafe923537eeb3aa880
 SHA512:
-  metadata.gz: e0e993ff5247dcb1acd76acbecaa2f0b65fcdf30e94d4342c8f362bc2ce0c87edf8ca2c511e35cf791a9150be29ff3f6f633f0b8d815ed7c3ae08dfff71d50f5
-  data.tar.gz: 34c05bb3bb1399be9c9d060617ad41cfcf8c2714c094097c5868fd52b56525c3be2e59af5be28ee28a5369e3e254267c389b40b496011ca8213350168c3ea7d6
+  metadata.gz: c113bc5af055eae0d038c42113fade624505848db7945576fd642845e7071791bf041db388e8ef8ff8b076a27a82b2de94beb8cf91ec80d8f02b478152d7ce4d
+  data.tar.gz: 77f0728d85424f45a5cf5c034f4b7a7510a54357a0e55bebfdd95a4f1c3da7a32517e4bc5d33d86d776d0d5245581fea71c2d163ff419da53d41d12b1ae8c6a2

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [0.11.0](https://github.com/dougyouch/schema/compare/v0.10.0...v0.11.0) (2026-10-05)
+
+
+### ⚠ BREAKING CHANGES
+
+* **gem:** Ruby 3.2 reached end of life in March 2026 and is no longer supported. CI now tests Ruby 3.3 and the .ruby-version Ruby, both with Gemfile.lock and the coverage gate.
+
+### Build System
+
+* **gem:** require ruby 3.3 ([412cb95](https://github.com/dougyouch/schema/commit/412cb95c84f26623fb9b3d67257f3339390e952f))
+
+## [0.10.0](https://github.com/dougyouch/schema/compare/v0.9.1...v0.10.0) (2026-10-04)
+
+
+### ⚠ BREAKING CHANGES
+
+* **parsers:** string_or_nil now returns nil for whitespace-only strings such as "   ", matching how blank strings parse for the other types. Other strings are still kept as is.
+
+### Features
+
+* **model:** add as_json only_set and handle input that is not a hash ([bdda922](https://github.com/dougyouch/schema/commit/bdda922bd6e4b7fbb2c31e0ada74596b67a3d5e7))
+* **parsers:** treat whitespace-only strings as nil for string_or_nil ([7313c99](https://github.com/dougyouch/schema/commit/7313c99bb0de5e340ad92cc958a1b601a5e3e15c))
+
+
+### Bug Fixes
+
+* **arrays:** raise a clear error for has_many without size ([617cb89](https://github.com/dougyouch/schema/commit/617cb89d9cbb028560d2148d4450e7d77689b877))
+* **cli:** report malformed json without a backtrace ([fc2f1f9](https://github.com/dougyouch/schema/commit/fc2f1f95df5681184cc80850a18d40cffeede121))
+* **csv:** strip the utf-8 byte order mark and handle empty header cells ([ad0216d](https://github.com/dougyouch/schema/commit/ad0216d429c881582d949ee2785e2e729d28bd23))
+
 ## [0.9.1](https://github.com/dougyouch/schema/compare/v0.9.0...v0.9.1) (2026-10-04)
 
 

data/README.md

@@ -6,9 +6,11 @@ A powerful Ruby gem for data transformation, validation, and type safety. Schema
 [![Coverage](https://raw.githubusercontent.com/dougyouch/schema/badges/coverage.svg)](https://github.com/dougyouch/schema/actions/workflows/ci.yml)
 [![Branch Coverage](https://raw.githubusercontent.com/dougyouch/schema/badges/branches.svg)](https://github.com/dougyouch/schema/actions/workflows/ci.yml)
 
+[API reference](https://rubydoc.info/gems/schema-model) · [Changelog](CHANGELOG.md) · [Architecture](ARCHITECTURE.md)
+
 ## Installation
 
-Requires Ruby 3.2 or newer. Add this line to your application's Gemfile:
+Requires Ruby 3.3 or newer. Add this line to your application's Gemfile:
 
 ```ruby
 gem 'schema-model'
@@ -181,6 +183,16 @@ 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.
 
+For nested input, `as_json(only_set: true)` keeps only the fields that were sent, at every level, so it can be merged into a JSON column without wiping fields the client left out:
+
+```ruby
+# body {"address": {"zip": null}}
+input.as_json(only_set: true)                                  # => { address: { zip: nil } }
+record.data = record.data.deep_merge(input.as_json(only_set: true).deep_stringify_keys)
+```
+
+`JSON.parse` returns an array, string or number for bodies that aren't JSON objects; `from_hash` records an `incompatible` error on `:base` for those instead of raising, so `parsed_and_valid?` handles them like any other bad input.
+
 ## Data Types
 
 ### Basic Types
@@ -190,7 +202,7 @@ attribute :name, :string              # String values
 attribute :count, :integer            # Integer values (parses "123", " 123 " and "0123" to 123)
 attribute :price, :float              # Float values (parses "9.99" to 9.99, also "1e+5")
 attribute :active, :boolean           # see below
-attribute :notes, :string_or_nil      # String, but returns nil if empty
+attribute :notes, :string_or_nil      # String, but nil when empty or whitespace-only
 ```
 
 Booleans accept `1, t, true, on, y, yes` as `true` and `0, f, false, off, n, no` as `false` (any case). Any other string is an `invalid` parsing error, and numbers are `true` unless they're 0.
@@ -533,6 +545,9 @@ user.as_json(include_nils: true)      # => { name: "John", email: nil }
 # Filter fields
 user.as_json(select_filter: ->(name, value, opts) { name == :name })
 user.as_json(reject_filter: ->(name, value, opts) { value.nil? })
+
+# Only the fields present in the input, at every level (nils that were sent are kept)
+user.as_json(only_set: true)          # => { name: "John", email: nil }
 ```
 
 ### Comparing, Inspecting and Copying
@@ -619,11 +634,11 @@ end
 UserSchema.to_headers  # => [..., "phones[1].number", "phones[2].number", "phones[3].number"]
 ```
 
-`to_a` writes at most `size` entries: a model with more entries than that has the extra ones left out of the array, with no error, so pick a `size` large enough for your data.
+Without `size:`, these methods raise an `ArgumentError` naming the association. `to_a` writes at most `size` entries: a model with more entries than that has the extra ones left out of the array, with no error, so pick a `size` large enough for your data.
 
 ### Schema::CSVParser
 
-`Schema::CSVParser` is a class that reads rows from a `CSV` object into models. The model needs `Schema::ArrayHeaders` and `Schema::Arrays`. Pass a plain `CSV` (not one created with `headers: true`); the first row is used as the headers unless you pass them in:
+`Schema::CSVParser` is a class that reads rows from a `CSV` object into models. The model needs `Schema::ArrayHeaders` and `Schema::Arrays`. Pass a plain `CSV` (not one created with `headers: true`); the first row is used as the headers unless you pass them in. Headers are stripped, and the byte order mark Excel puts at the start of UTF-8 files is removed:
 
 ```ruby
 require 'csv'

data/bin/schema-json2csv

@@ -61,7 +61,11 @@ io = csv_file ? File.open(csv_file, 'ab') : $stdout
 
 io.print CSV.generate_line(schema_class.to_headers) if write_headers
 
-json_data = JSON.parse(json_data)
+begin
+  json_data = JSON.parse(json_data)
+rescue JSON::ParserError => e
+  abort("invalid json: #{e.message.lines.first.strip}")
+end
 json_data = [json_data] unless json_data.is_a?(Array)
 
 json_data.each do |data|

data/lib/schema/active_model_parsing_errors.rb

@@ -6,6 +6,7 @@ module Schema
   # Schema::ActiveModelParsingErrors turns parsing error codes into readable messages,
   # e.g. "Age is invalid" instead of "Age invalid". Override them with I18n keys under schema.parsing_errors.
   class ActiveModelParsingErrors < ActiveModel::Errors
+    # Default English message for each parsing error code.
     MESSAGES = {
       ::Schema::ParsingErrors::INVALID => 'is invalid',
       ::Schema::ParsingErrors::INCOMPATIBLE => 'is an incompatible type',

data/lib/schema/active_model_validations.rb

@@ -20,6 +20,10 @@ module Schema
       )
     end
 
+    # Raises unless the model parsed cleanly and passes its validations.
+    # @raise [ParsingException] when there are parsing errors
+    # @raise [ValidationException] when validations fail
+    # @return [void]
     def valid!
       parsed!
       valid_model!
@@ -38,6 +42,7 @@ module Schema
 
     # no-doc
     module OverrideParsingErrors
+      # @return [ActiveModelParsingErrors] parsing errors with readable messages
       def parsing_errors
         @parsing_errors ||= ActiveModelParsingErrors.new(self)
       end

data/lib/schema/array_headers.rb

@@ -9,6 +9,10 @@ module Schema
 
     # adds methods to the class
     module ClassMethods
+      # Maps header names to the attributes they fill.
+      # @param headers [Array<String>] the header row
+      # @param header_prefix [String, nil] used internally for has_many columns
+      # @return [Hash] e.g. `{ name: { index: 0 }, phones: { number: { indexes: [1, 2] } } }`
       def map_headers_to_attributes(headers, header_prefix = nil)
         mapped_headers = {}
         map_headers_to_fields(headers, mapped_headers, header_prefix)
@@ -17,14 +21,24 @@ module Schema
         mapped_headers
       end
 
+      # Names of the fields no header was mapped to.
+      # @param mapped_headers [Hash] result of {#map_headers_to_attributes}
+      # @param header_prefix [String, nil] used internally for nested associations
+      # @return [Array<String>]
       def get_unmapped_field_names(mapped_headers, header_prefix = nil)
         get_field_names(mapped_headers, header_prefix, false)
       end
 
+      # Names of the fields the headers were mapped to, as they'd appear in a header row.
+      # @param mapped_headers [Hash] result of {#map_headers_to_attributes}
+      # @param header_prefix [String, nil] used internally for nested associations
+      # @return [Array<String>]
       def get_mapped_field_names(mapped_headers, header_prefix = nil)
         get_field_names(mapped_headers, header_prefix, true)
       end
 
+      # Field names (first alias preferred) that are, or with mapped false are not, in the mapping.
+      # @api private
       def get_field_names(mapped_headers, header_prefix = nil, mapped = true)
         fields = []
         schema.each do |field_name, field_options|
@@ -41,6 +55,7 @@ module Schema
         fields
       end
 
+      # Highest has_many index looked for in headers such as Phones1Number.
       MAX_ARRAY_INDEX = 10_000
 
       private

data/lib/schema/arrays.rb

@@ -7,12 +7,26 @@ module Schema
       base.extend ClassMethods
     end
 
+    # the fixed number of entries a has_many takes up in an array
+    def self.association_size(field_options)
+      field_options[:size] || raise(
+        ArgumentError,
+        "has_many #{field_options[:name].inspect} needs a size: option to be converted to and from arrays"
+      )
+    end
+
     # adds from_array method to the class
     module ClassMethods
+      # Builds a model from a row.
+      # @param array [Array] row values
+      # @param mapped_headers [Hash] result of ArrayHeaders::ClassMethods#map_headers_to_attributes
+      # @return [Schema::Model]
       def from_array(array, mapped_headers)
         new.update_attributes_with_array(array, mapped_headers)
       end
 
+      # An array of nils shaped like {Schema::Arrays#to_a}'s output.
+      # @return [Array]
       def to_empty_array
         data = []
         schema.each_value do |field_options|
@@ -23,12 +37,15 @@ module Schema
             when :has_one
               const_get(field_options[:class_name]).to_empty_array
             when :has_many
-              field_options[:size].times.map { const_get(field_options[:class_name]).to_empty_array }
+              Arrays.association_size(field_options).times.map { const_get(field_options[:class_name]).to_empty_array }
             end
         end
         data
       end
 
+      # Header names in array order, e.g. `phones[1].number`.
+      # @param prefix [String, nil] used internally for nested associations
+      # @return [Array<String>]
       def to_headers(prefix = nil)
         headers = []
         schema.each_value do |field_options|
@@ -39,7 +56,7 @@ module Schema
             when :has_one
               const_get(field_options[:class_name]).to_headers("#{prefix}#{field_options[:key]}.")
             when :has_many
-              field_options[:size].times.map do |i|
+              Arrays.association_size(field_options).times.map do |i|
                 const_get(field_options[:class_name]).to_headers(prefix.to_s + field_options[:key] + "[#{i + 1}].")
               end
             else
@@ -50,6 +67,8 @@ module Schema
       end
     end
 
+    # The model as a nested array, in {ClassMethods#to_headers} order; has_many entries beyond size: are left out.
+    # @return [Array]
     def to_a
       data = []
       self.class.schema.each_value do |field_options|
@@ -62,7 +81,7 @@ module Schema
             value ? value.to_a : self.class.const_get(field_options[:class_name]).to_empty_array
           when :has_many
             values = value || []
-            field_options[:size].times.map do |idx|
+            Arrays.association_size(field_options).times.map do |idx|
               value = values[idx]
               value ? value.to_a : self.class.const_get(field_options[:class_name]).to_empty_array
             end
@@ -73,6 +92,11 @@ module Schema
       data
     end
 
+    # Sets attributes from a row using a header mapping.
+    # @param array [Array] row values
+    # @param mapped_headers [Hash] result of ArrayHeaders::ClassMethods#map_headers_to_attributes
+    # @param offset [Integer, nil] has_many entry index, used internally
+    # @return [self]
     def update_attributes_with_array(array, mapped_headers, offset = nil)
       self.class.schema.each_value do |field_options|
         next unless (mapped_field = mapped_headers[field_options[:name]])
@@ -95,11 +119,15 @@ module Schema
       self
     end
 
+    # Builds nested models from a row.
+    # @api private
     def update_nested_schemas_from_array(array, mapped_headers, current_offset = nil)
       update_nested_has_one_associations_from_array(array, mapped_headers, current_offset)
       update_nested_has_many_associations_from_array(array, mapped_headers)
     end
 
+    # Builds has_one models from a row.
+    # @api private
     def update_nested_has_one_associations_from_array(array, mapped_headers, current_offset = nil)
       self.class.schema.each_value do |field_options|
         next unless field_options[:type] == :has_one
@@ -112,6 +140,8 @@ module Schema
       end
     end
 
+    # Builds has_many models from a row.
+    # @api private
     def update_nested_has_many_associations_from_array(array, mapped_headers)
       self.class.schema.each_value do |field_options|
         next unless field_options[:type] == :has_many
@@ -128,10 +158,14 @@ module Schema
       end
     end
 
+    # Builds one nested model from a row.
+    # @api private
     def create_schema_with_array(field_options, array, mapped_model, offset)
       self.class.const_get(field_options[:class_name]).new.update_attributes_with_array(array, mapped_model, offset)
     end
 
+    # Number of has_many entries a mapping has columns for.
+    # @api private
     def largest_number_of_indexes_from_map(mapped_model)
       size = 0
       mapped_model.each_value do |info|

data/lib/schema/associations/base.rb

@@ -19,10 +19,12 @@ module Schema
           @base_schema_class_name = kls.name
         end
 
+        # @return [Class] the class that declared this association
         def base_schema_class
           @base_schema_class_name ? Object.const_get(@base_schema_class_name) : @base_schema_class
         end
 
+        # @return [Hash] the association's options in the parent schema
         def schema_options
           base_schema_class.schema[schema_name]
         end

data/lib/schema/associations/dynamic_types.rb

@@ -10,6 +10,11 @@ module Schema
 
       # no-doc
       module ClassMethods
+        # Declares a subtype, used when the type field equals type.
+        # @param type [String, Symbol] type field value
+        # @param options [Hash] `class_name:` to name the generated class
+        # @yield attribute definitions for this type
+        # @return [Class] the subtype class
         def add_type(type, options = {}, &block)
           class_name = options[:class_name] || schema_dynamic_type_class_name(type)
           kls = Class.new(self)
@@ -19,14 +24,20 @@ module Schema
           kls
         end
 
+        # Declares the subtype used when no other type matches.
+        # @param options [Hash] see {#add_type}
+        # @yield attribute definitions for this type
+        # @return [Class] the subtype class
         def default_type(options = {}, &)
           add_type(:default, options, &)
         end
 
+        # @return [Hash] type name => class name, including :default
         def dynamic_types
           schema_options[:types]
         end
 
+        # @return [Array] declared type names, without :default
         def dynamic_type_names
           dynamic_types.keys - [:default]
         end

data/lib/schema/associations/has_many.rb

@@ -10,6 +10,13 @@ module Schema
 
       # no-doc
       module ClassMethods
+        # Declares a list of nested models, with a getter, a setter and append_to_<name>.
+        # @param name [Symbol]
+        # @param options [Hash] `alias:`/`aliases:`, `default: true`, `class_name:`, `base_class:`,
+        #   `from: :hash` with `hash_key_field:`, `size:` (for Schema::Arrays), and
+        #   `type_field:`/`external_type_field:`/`type_ignorecase:` for dynamic types
+        # @yield attribute definitions for the nested model
+        # @return [Class] the nested model class
         def has_many(name, options = {}, &block)
           options = ::Schema::Utils.add_association_class(self, name, :has_many, options)
 

data/lib/schema/associations/has_one.rb

@@ -10,6 +10,12 @@ module Schema
 
       # no-doc
       module ClassMethods
+        # Declares a nested model, with a getter and a setter.
+        # @param name [Symbol]
+        # @param options [Hash] `alias:`/`aliases:`, `default: true`, `class_name:`, `base_class:`, and
+        #   `type_field:`/`external_type_field:`/`type_ignorecase:` for dynamic types
+        # @yield attribute definitions for the nested model
+        # @return [Class] the nested model class
         def has_one(name, options = {}, &block)
           options = ::Schema::Utils.add_association_class(self, name, :has_one, options)
 

data/lib/schema/associations/schema_creator.rb

@@ -16,6 +16,8 @@ module Schema
         configure_dynamic_schema_options(options)
       end
 
+      # Builds one nested model, recording parsing errors on base_schema.
+      # @api private
       def create_schema(base_schema, data, error_name = nil, skip_fields = [])
         if data.is_a?(Hash)
           unless (schema_class = get_schema_class(base_schema, data))
@@ -31,6 +33,8 @@ module Schema
         end
       end
 
+      # Builds a has_many list from an array, or from a hash with `from: :hash`.
+      # @api private
       def create_schemas(base_schema, list, skip_fields = [])
         if is_list? && list.is_a?(Array)
           list.each_with_index.map { |data, idx| create_schema(base_schema, data, "#{@schema_name}:#{idx}", skip_fields) }
@@ -46,6 +50,8 @@ module Schema
         end
       end
 
+      # The class to build for data, choosing a dynamic type when configured.
+      # @api private
       def get_schema_class(base_schema, data)
         if dynamic?
           get_dynamic_schema_class(base_schema, data)
@@ -62,6 +68,8 @@ module Schema
         @is_list
       end
 
+      # The dynamic type class matching data's type.
+      # @api private
       def get_dynamic_schema_class(base_schema, data)
         type = get_dynamic_type(base_schema, data)
         type = type.to_s.downcase if @ignorecase
@@ -72,12 +80,16 @@ module Schema
         get_default_dynamic_schema_class(base_schema)
       end
 
+      # The default_type class, if one was declared.
+      # @api private
       def get_default_dynamic_schema_class(base_schema)
         return unless (class_name = @types[:default])
 
         base_schema.class.const_get(class_name)
       end
 
+      # The type value from the nested data or the parent's external type field.
+      # @api private
       def get_dynamic_type(base_schema, data)
         if @type_field
           type_fields.each do |name|
@@ -98,10 +110,14 @@ module Schema
         end
       end
 
+      # Records a parsing error on the parent model.
+      # @api private
       def add_parsing_error(base_schema, error_name, error_msg)
         base_schema.parsing_errors.add(error_name || @schema_name, error_msg)
       end
 
+      # Reads the dynamic type options.
+      # @api private
       def configure_dynamic_schema_options(options)
         @type_field = options[:type_field]
         @external_type_field = options[:external_type_field]

data/lib/schema/attribute_values.rb

@@ -18,6 +18,8 @@ module Schema
       set_field_options.to_h { |field_options| [field_options[:name], public_send(field_options[:getter])] }
     end
 
+    # @param other [Object]
+    # @return [Boolean] true for a model of the same class with equal attribute values
     def ==(other)
       other.instance_of?(self.class) && other.attribute_values == attribute_values
     end

data/lib/schema/csv_parser.rb

@@ -8,28 +8,45 @@ module Schema
     def initialize(csv, schema_class, headers = nil)
       @csv = csv
       @schema_class = schema_class
-      @headers = (headers || csv.shift) || []
-      @headers = @headers.map(&:strip)
+      @headers = clean_headers((headers || csv.shift) || [])
       @mapped_headers = schema_class.map_headers_to_attributes(@headers)
     end
 
+    # strips whitespace, treats empty header cells as "", and drops the UTF-8 byte order mark
+    # that Excel puts before the first header
+    def clean_headers(headers)
+      headers.map.with_index do |header, idx|
+        header = header.to_s.strip
+        idx.zero? ? header.delete_prefix("\uFEFF") : header
+      end
+    end
+
+    # Required header names the CSV doesn't map.
+    # @param required_fields [Array<String>]
+    # @return [Array<String>]
     def missing_fields(required_fields)
       required_fields - get_mapped_headers(@mapped_headers)
     end
     alias missing_headers missing_fields
 
+    # Reads the next row.
+    # @return [Schema::Model, nil] nil at the end of the CSV
     def shift
       return unless (row = @csv.shift)
 
       @schema_class.from_array(row, @mapped_headers)
     end
 
+    # Yields a model for each remaining row.
+    # @yieldparam model [Schema::Model]
     def each
       while (schema = shift)
         yield schema
       end
     end
 
+    # Header names covered by a mapping.
+    # @api private
     def get_mapped_headers(mapped_headers)
       indexed_headers = []
       mapped_headers.each_value do |info|

data/lib/schema/deep_copy.rb

@@ -3,6 +3,9 @@
 module Schema
   # Schema::DeepCopy copies a model along with its nested models, collections and parsing errors
   module DeepCopy
+    # Copies the model with its nested models, collections, strings and parsing errors,
+    # so the copy can be changed without touching the original.
+    # @return [Schema::Model]
     def deep_dup
       copy = dup
       copy.copy_attribute_values_from(self)

data/lib/schema/errors.rb

@@ -5,16 +5,23 @@ module Schema
   class Errors
     attr_reader :errors
 
+    # Returned by {#[]} for names without errors.
     EMPTY_ARRAY = [].freeze
 
     def initialize
       @errors = {}
     end
 
+    # @param name [Symbol, String]
+    # @return [Array<String>] error codes for name (empty when none)
     def [](name)
       @errors[name] || EMPTY_ARRAY
     end
 
+    # Records an error code for name.
+    # @param name [Symbol, String]
+    # @param error [String] a {Schema::ParsingErrors} code
+    # @return [Array<String>]
     def add(name, error)
       @errors[name] ||= []
       @errors[name] << error
@@ -25,6 +32,7 @@ module Schema
       @errors.empty?
     end
 
+    # @return [Array] names that have errors
     def attribute_names
       @errors.keys
     end

data/lib/schema/model.rb

@@ -14,6 +14,8 @@ module Schema
       base.extend ClassMethods
     end
 
+    # Options every attribute starts with.
+    # @api private
     def self.default_attribute_options(name, type)
       {
         key: name.to_s.freeze,
@@ -28,6 +30,7 @@ module Schema
 
     # no-doc
     module ClassMethods
+      # @return [Hash{Symbol => Hash}] field name => options, including alias entries
       def schema
         {}.freeze
       end
@@ -41,6 +44,8 @@ module Schema
         @schema_with_string_keys = current_schema.transform_keys(&:to_s).freeze
       end
 
+      # Modules to include in nested classes, and the unknown attribute setting.
+      # @api private
       def schema_config
         {
           schema_includes: [],
@@ -65,6 +70,12 @@ module Schema
         schema_config[:capture_unknown_attributes]
       end
 
+      # Declares an attribute with a getter, a parsing setter and a `<name>_was_set?` predicate.
+      # @param name [Symbol]
+      # @param type [Symbol] parsed by `parse_<type>`, e.g. :integer
+      # @param options [Hash] `alias:`/`aliases:`, `default:`, and parser options such as
+      #   `separator:`/`data_type:` for :array
+      # @return [void]
       def attribute(name, type, options = {})
         options[:aliases] = [options[:alias]] if options.key?(:alias)
 
@@ -79,10 +90,15 @@ module Schema
         add_aliases(name, options)
       end
 
+      # Builds a model from data. See {Schema::Model#update_attributes}.
+      # @return [Schema::Model]
       def from_hash(data = nil, skip_fields = [])
         new.update_attributes(data, skip_fields)
       end
 
+      # Includes mod here and in every nested association class, current and future.
+      # @param mod [Module]
+      # @return [void]
       def schema_include(mod)
         config = schema_config.dup
         config[:schema_includes] = config[:schema_includes] + [mod]
@@ -96,6 +112,8 @@ module Schema
         end
       end
 
+      # Defines an attribute's getter, setter and predicate.
+      # @api private
       def add_attribute_methods(name, options)
         parser_check = parser_check_code(name, options)
         class_eval(
@@ -123,6 +141,8 @@ module Schema
         "::Schema::Utils.check_parser!(self, #{options[:parser].inspect}, #{name.inspect}, #{options[:type].inspect})"
       end
 
+      # Adds schema entries and methods for an attribute's aliases.
+      # @api private
       def add_aliases(name, options)
         return unless options[:aliases]
 
@@ -134,32 +154,47 @@ module Schema
       end
     end
 
+    # Sets attributes, then associations, from data.
+    # @param data [Hash, Array, nil] a hash with symbol or string keys, or [key, value] pairs;
+    #   anything else records an incompatible error on :base
+    # @param skip_fields [Array] fields to ignore, e.g. `[:id, { items: [:id] }]`
+    # @return [self]
     def update_attributes(data = nil, skip_fields = [])
       return self if data.nil?
+      return add_incompatible_data_error unless attributes_data?(data)
 
       update_model_attributes(data, skip_fields)
       update_associations(data, skip_fields)
       self
     end
 
+    # The model as a hash; nested models become hashes.
+    # @param opts [Hash]
+    # @option opts [Boolean] :include_nils include nil values
+    # @option opts [Boolean] :only_set include only fields present in the input (nils included), at every level
+    # @option opts [Proc] :select_filter keep a field when it returns true; called with (name, value, options)
+    # @option opts [Proc] :reject_filter drop a field when it returns true; called with (name, value, options)
+    # @return [Hash]
     def as_json(opts = {})
       self.class.schema.each_with_object({}) do |(field_name, field_options), memo|
         next if field_options[:alias_of]
+        next if opts[:only_set] && !instance_variable_defined?(field_options[:instance_variable])
 
         value = public_send(field_options[:getter])
-        next if value.nil? && !opts[:include_nils]
-        next if opts[:select_filter] && !opts[:select_filter].call(field_name, value, field_options)
-        next if opts[:reject_filter]&.call(field_name, value, field_options)
+        next unless include_in_json?(field_name, value, field_options, opts)
 
         memo[field_name] = value.is_a?(Array) ? value.map { |e| value_as_json(e, opts) } : value_as_json(value, opts)
       end
     end
 
+    # {#as_json} with nil values included.
+    # @return [Hash]
     def to_hash
       as_json(include_nils: true)
     end
     alias to_h to_hash
 
+    # @return [Schema::Errors] parsing error codes by field
     def parsing_errors
       @parsing_errors ||= Errors.new
     end
@@ -172,6 +207,26 @@ module Schema
 
     private
 
+    # a Hash (or anything with each_pair), or an array of [key, value] pairs
+    def attributes_data?(data)
+      return true if data.respond_to?(:each_pair)
+
+      data.is_a?(Array) && data.all? { |pair| pair.is_a?(Array) && pair.size == 2 }
+    end
+
+    def add_incompatible_data_error
+      parsing_errors.add(:base, ::Schema::ParsingErrors::INCOMPATIBLE)
+      self
+    end
+
+    # only_set keeps nils that came from the input, since they mean "set to null"
+    def include_in_json?(field_name, value, field_options, opts)
+      return false if value.nil? && !opts[:include_nils] && !opts[:only_set]
+      return false if opts[:select_filter] && !opts[:select_filter].call(field_name, value, field_options)
+
+      !opts[:reject_filter]&.call(field_name, value, field_options)
+    end
+
     # values without as_json (no ActiveSupport JSON extension) are returned as is
     def value_as_json(value, opts)
       value.respond_to?(:as_json) ? value.as_json(opts) : value

data/lib/schema/parsers/american.rb

@@ -8,9 +8,13 @@ module Schema
     module American
       include StringValue
 
+      # strptime format for :american_date.
       DATE_FORMAT = '%m/%d/%Y'
+      # strptime format for :american_time.
       TIME_FORMAT = '%m/%d/%Y %H:%M:%S'
 
+      # Parses MM/DD/YYYY strings; blank strings are nil.
+      # @return [Date, nil]
       def parse_american_date(field_name, parsing_errors, value)
         case value
         when Date
@@ -27,6 +31,8 @@ module Schema
         end
       end
 
+      # Parses MM/DD/YYYY HH:MM:SS strings; blank strings are nil.
+      # @return [Time, nil]
       def parse_american_time(field_name, parsing_errors, value)
         case value
         when Time

data/lib/schema/parsers/array.rb

@@ -4,6 +4,9 @@ module Schema
   module Parsers
     # Schema::Parsers::Array adds the array type to schemas
     module Array
+      # Parses arrays, or strings split on the attribute's `separator:`, converting
+      # elements with its `data_type:`.
+      # @return [Array, nil]
       def parse_array(field_name, parsing_errors, value)
         case value
         when ::Array
@@ -25,12 +28,16 @@ module Schema
         end
       end
 
+      # Splits a string on the attribute's separator.
+      # @api private
       def self.parse_string_array(model, field_name, parsing_errors, value, schema_options)
         return nil unless (separator = schema_options[:separator])
 
         convert_array_values(model, field_name, parsing_errors, value.split(separator), schema_options)
       end
 
+      # Converts elements with the attribute's data_type.
+      # @api private
       def self.convert_array_values(model, field_name, parsing_errors, data, schema_options)
         return data unless (data_type = schema_options[:data_type])
 

data/lib/schema/parsers/common.rb

@@ -10,6 +10,7 @@ module Schema
 
       # strings are stripped first; a blank string parses to nil without an error
       INTEGER_REGEX = /\A[-+]?\d+(?:\.0+)?\z/
+      # Accepted float strings, e.g. "1.5", "007.5", "1e+5".
       FLOAT_REGEX = /\A[-+]?\d+(?:\.\d+)?([Ee][-+]?\d+)?\z/
       # matched case-insensitively; any other string is invalid
       BOOLEAN_STRINGS = {
@@ -17,6 +18,8 @@ module Schema
         '0' => false, 'f' => false, 'false' => false, 'off' => false, 'n' => false, 'no' => false
       }.freeze
 
+      # Parses integers; whole floats are converted, fractional ones are incompatible.
+      # @return [Integer, nil]
       def parse_integer(field_name, parsing_errors, value)
         case value
         when Integer
@@ -35,6 +38,8 @@ module Schema
         end
       end
 
+      # Converts a float for parse_integer.
+      # @api private
       def parse_float_as_integer(field_name, parsing_errors, value)
         unless value.finite?
           parsing_errors.add(field_name, ::Schema::ParsingErrors::INCOMPATIBLE)
@@ -45,6 +50,8 @@ module Schema
         value.to_i
       end
 
+      # Converts scalars to strings; hashes and arrays are incompatible.
+      # @return [String, nil]
       def parse_string(field_name, parsing_errors, value)
         case value
         when String
@@ -59,11 +66,11 @@ module Schema
         end
       end
 
-      # if the string is empty return nil
+      # a blank (empty or whitespace-only) string returns nil; other strings are kept as is
       def parse_string_or_nil(field_name, parsing_errors, value)
         case value
         when String
-          value.empty? ? nil : value
+          value.strip.empty? ? nil : value
         when ::Hash, ::Array
           parsing_errors.add(field_name, ::Schema::ParsingErrors::INCOMPATIBLE)
           nil
@@ -74,6 +81,8 @@ module Schema
         end
       end
 
+      # Parses floats.
+      # @return [Float, nil]
       def parse_float(field_name, parsing_errors, value)
         case value
         when Float
@@ -92,6 +101,8 @@ module Schema
         end
       end
 
+      # Parses ISO 8601 date-times (Time.xmlschema).
+      # @return [Time, nil]
       def parse_time(field_name, parsing_errors, value)
         case value
         when Time
@@ -108,6 +119,8 @@ module Schema
         end
       end
 
+      # Parses ISO 8601 dates (Date.iso8601).
+      # @return [Date, nil]
       def parse_date(field_name, parsing_errors, value)
         case value
         when Date
@@ -124,6 +137,8 @@ module Schema
         end
       end
 
+      # Parses booleans; see {BOOLEAN_STRINGS}. Numbers are true unless 0.
+      # @return [Boolean, nil]
       def parse_boolean(field_name, parsing_errors, value)
         case value
         when TrueClass, FalseClass

data/lib/schema/parsers/hash.rb

@@ -4,6 +4,8 @@ module Schema
   module Parsers
     # Schema::Parsers::Hash adds the hash type to schemas
     module Hash
+      # Accepts hashes; anything else is incompatible.
+      # @return [Hash, nil]
       def parse_hash(field_name, parsing_errors, value)
         case value
         when ::Hash

data/lib/schema/parsers/json.rb

@@ -6,6 +6,8 @@ module Schema
   module Parsers
     # Schema::Parsers::Json parse the string as json
     module Json
+      # Parses JSON strings.
+      # @return [Object, nil] the parsed JSON
       def parse_json(field_name, parsing_errors, value)
         case value
         when String

data/lib/schema/parsing_errors.rb

@@ -3,10 +3,15 @@
 module Schema
   # Schema::ParsingErrors is a collection of parsing error messages
   module ParsingErrors
+    # The value couldn't be parsed.
     INVALID = 'invalid'
+    # The value is the wrong kind, e.g. a hash for a string attribute.
     INCOMPATIBLE = 'incompatible'
+    # No dynamic type matched the type field.
     UNKNOWN = 'unknown'
+    # The key isn't in the schema.
     UNKNOWN_ATTRIBUTE = 'unknown_attribute'
+    # The parser doesn't handle the value's class.
     UNHANDLED_TYPE = 'unhandled_type'
   end
 end

data/lib/schema/utils.rb

@@ -13,10 +13,14 @@ module Schema
             "no #{parser} method (schema_include the parser module that defines it)"
     end
 
+    # Turns a name into a constant name.
+    # @api private
     def classify_name(name)
       name.gsub(/[^\da-z_-]/, '').gsub(/(^.|[_|-].)/) { |m| m[-1].upcase }
     end
 
+    # Creates and registers an association's model class.
+    # @api private
     def create_schema_class(base_schema_class, schema_name, options)
       base_schema_class.add_value_to_class_method(:schema, schema_name => options)
       kls = Class.new(options[:base_class] || Object)
@@ -26,6 +30,8 @@ module Schema
       kls
     end
 
+    # Includes Schema::Model and the parent's schema_include modules.
+    # @api private
     def include_schema_modules(kls, schema_config)
       kls.send(:include, ::Schema::Model)
       schema_config[:schema_includes].each do |mod|
@@ -33,6 +39,8 @@ module Schema
       end
     end
 
+    # Builds an association's schema options.
+    # @api private
     def association_options(schema_name, schema_type, options)
       options[:class_name] ||= "Schema#{classify_name(schema_type.to_s)}#{classify_name(schema_name.to_s)}"
       options[:association] = true
@@ -41,6 +49,8 @@ module Schema
       ::Schema::Model.default_attribute_options(schema_name, schema_type).merge(options)
     end
 
+    # Sets up an association's class and options.
+    # @api private
     def add_association_class(base_schema_class, schema_name, schema_type, options)
       options = ::Schema::Utils.association_options(schema_name, schema_type, options)
       kls = ::Schema::Utils.create_schema_class(
@@ -53,12 +63,16 @@ module Schema
       options
     end
 
+    # Links an association class to its parent.
+    # @api private
     def add_association_defaults(kls, base_schema_class, schema_name)
       kls.send(:include, ::Schema::Associations::Base)
       kls.base_schema_class = base_schema_class
       kls.schema_name = schema_name
     end
 
+    # Adds dynamic type support when configured.
+    # @api private
     def add_association_dynamic_types(kls, options)
       return if !options[:type_field] && !options[:external_type_field]
 
@@ -92,6 +106,8 @@ module Schema
       value.dup
     end
 
+    # Defines an attribute's default method and getter.
+    # @api private
     def add_attribute_default_methods(kls, options)
       default = options[:default]
       kls.send(:define_method, options[:default_method]) { ::Schema::Utils.copy_default(default) }

data/lib/schema/version.rb

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

data/lib/schema-model.rb

@@ -4,6 +4,7 @@ autoload :SchemaValidator, 'schema_validator'
 
 # Schema is a series of tools for transforming data into models
 module Schema
+  # Base error for parsed! and valid_model!; carries the model and its errors.
   class SchemaException < StandardError
     attr_reader :schema,
                 :errors
@@ -15,7 +16,9 @@ module Schema
     end
   end
 
+  # Raised by parsed! (and valid!) when the model has parsing errors.
   class ParsingException < SchemaException; end
+  # Raised by valid_model! (and valid!) when the model fails its validations.
   class ValidationException < SchemaException; end
 
   # raised when a value is assigned to an attribute whose type has no parse_<type> method

data/lib/schema_validator.rb

@@ -2,6 +2,8 @@
 
 # SchemaValidator validates nested schemas: each one must have no parsing errors and pass its validations
 class SchemaValidator < ActiveModel::EachValidator
+  # Called by ActiveModel for `validates :x, schema: true`.
+  # @api private
   def validate_each(record, attribute, value)
     record.errors.add(attribute, options.fetch(:message, :invalid)) unless valid_schema?(value)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schema-model
 version: !ruby/object:Gem::Version
-  version: 0.9.1
+  version: 0.11.0
 platform: ruby
 authors:
 - Doug Youch
@@ -15,14 +15,20 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '0.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 description: Declare typed attributes and Schema turns incoming hashes, JSON and CSV
   rows into Ruby objects. Values are coerced to integers, floats, booleans, dates,
   times, arrays and hashes, and bad input is recorded as parsing errors instead of
@@ -73,6 +79,7 @@ metadata:
   source_code_uri: https://github.com/dougyouch/schema
   changelog_uri: https://github.com/dougyouch/schema/blob/master/CHANGELOG.md
   bug_tracker_uri: https://github.com/dougyouch/schema/issues
+  documentation_uri: https://rubydoc.info/gems/schema-model
 rdoc_options: []
 require_paths:
 - lib
@@ -80,7 +87,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="