odin-foundation 1.0.4 → 1.2.0

data/lib/odin/forms.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require_relative "forms/types"
+require_relative "forms/units"
+require_relative "forms/accessibility"
+require_relative "forms/css"
+require_relative "forms/parser"
+require_relative "forms/renderer"
+
+module Odin
+  # ODIN Forms — parse and render declarative form definitions.
+  module Forms
+    class << self
+      # Parse ODIN forms text into a typed OdinForm.
+      def parse_form(text)
+        text = text.encode("UTF-8") if text.is_a?(String) && text.encoding != Encoding::UTF_8
+        Parser.new.parse(text)
+      end
+
+      # Render an OdinForm to a complete HTML string. +data+ is an optional
+      # OdinDocument bound to field values; +options+ accepts :className.
+      def render_form(form, data = nil, options = nil)
+        Renderer.new.render(form, data, options)
+      end
+
+      def generate_form_css
+        Css.generate_form_css
+      end
+
+      def generate_print_css
+        Css.generate_print_css
+      end
+
+      def to_pixels(value, unit)
+        Units.to_pixels(value, unit)
+      end
+
+      def from_pixels(px, unit)
+        Units.from_pixels(px, unit)
+      end
+
+      def generate_field_id(element_name, page_index)
+        Accessibility.generate_field_id(element_name, page_index)
+      end
+
+      def contrast_ratio(fg, bg)
+        Accessibility.contrast_ratio(fg, bg)
+      end
+
+      def meets_contrast_aa(fg, bg, font_size)
+        Accessibility.meets_contrast_aa(fg, bg, font_size)
+      end
+    end
+  end
+end

data/lib/odin/parsing/parser.rb

@@ -32,6 +32,7 @@ module Odin
         @tabular_columns = []
         @tabular_array_path = ""
         @tabular_row_index = 0
+        @pre_tabular_context = nil
 
         # Document chaining
         @documents = []
@@ -51,7 +52,7 @@ module Odin
             break
           when TokenType::NEWLINE
             @pos += 1
-            # Blank line after {$} metadata exits metadata mode (Java parity)
+            # Blank line after {$} metadata exits metadata mode
             if @metadata_mode && @context.empty?
               nt = @tokens[@pos]
               if nt && nt.type == TokenType::NEWLINE
@@ -279,6 +280,10 @@ module Odin
       end
 
       def setup_tabular(array_path, columns_str, token)
+        # Section context to restore when the tabular block ends and a top-level
+        # assignment follows.
+        @pre_tabular_context = @context
+
         # Relative paths (starting with .) resolve relative to previous context
         # Absolute paths are used as-is (same logic as resolve_header_path)
         resolved_path = if array_path.start_with?(".")
@@ -334,6 +339,9 @@ module Odin
 
       def exit_tabular_mode!
         return unless @tabular_mode
+        # Restore the pre-tabular section context once data rows have been read, so
+        # a following top-level assignment is not nested under the array path.
+        @context = @pre_tabular_context if @tabular_row_index.positive? && !@pre_tabular_context.nil?
         @tabular_mode = false
         @tabular_primitive = false
         @tabular_columns = []
@@ -393,6 +401,22 @@ module Odin
         # Track array indices
         track_array_index(full_path, path_token)
 
+        # Top-level metadata assignment ($.key = value), e.g. from canonical output
+        if !@metadata_mode && (full_path.start_with?("$.") || full_path == "$")
+          meta_key = full_path.start_with?("$.") ? full_path[2..] : ""
+          unless meta_key.empty?
+            if @current_metadata.key?(meta_key)
+              raise Errors::ParseError.new(
+                Errors::ParseErrorCode::DUPLICATE_PATH_ASSIGNMENT,
+                path_token.line, path_token.column,
+                "Duplicate metadata key: #{meta_key}"
+              )
+            end
+            @current_metadata[meta_key] = value
+          end
+          return
+        end
+
         if @metadata_mode
           # Check duplicate in metadata
           if @current_metadata.key?(full_path)

data/lib/odin/parsing/tokenizer.rb

@@ -196,6 +196,8 @@ module Odin
             scan_identifier(line, col)
           when 38 # &
             scan_identifier(line, col)
+          when 36 # $
+            scan_meta_path(line, col)
           when 91 # [
             scan_array_indexed_path(line, col)
           else
@@ -470,43 +472,33 @@ module Odin
         emit(TokenType::ERROR, "Unterminated string", line, col)
       end
 
+      # Triple-quoted string. Content is captured verbatim (no escape processing,
+      # no newline trimming) and may span newlines; closes at the next """.
       def scan_multiline_string(line, col)
         s = @scanner
-        # Skip initial newline after opening """
-        if !s.eos?
-          byte = s.string.getbyte(s.pos)
-          if byte == 10
-            s.pos += 1; @line += 1; @col = 1
-          elsif byte == 13
-            s.pos += 1; @line += 1; @col = 1
-            if !s.eos? && s.string.getbyte(s.pos) == 10
-              s.pos += 1
-            end
-          end
-        end
-
         result = +""
         until s.eos?
           # Check for closing """
           if s.string.getbyte(s.pos) == 34 &&
-             s.pos + 2 < s.string.bytesize &&
              s.string.getbyte(s.pos + 1) == 34 &&
              s.string.getbyte(s.pos + 2) == 34
             s.pos += 3; @col += 3
-            emit(TokenType::STRING, result, line, col)
+            emit(TokenType::STRING, result, line, col, raw: "multiline")
             return
           end
 
           byte = s.string.getbyte(s.pos)
-          if byte == 13 # \r
+          if byte == 10 # \n
             result << "\n"
             s.pos += 1; @line += 1; @col = 1
+          elsif byte == 13 # \r
+            s.pos += 1; @line += 1; @col = 1
             if !s.eos? && s.string.getbyte(s.pos) == 10
+              result << "\n"
               s.pos += 1
+            else
+              result << "\r"
             end
-          elsif byte == 10 # \n
-            result << "\n"
-            s.pos += 1; @line += 1; @col = 1
           else
             # Scan non-special chars in bulk
             chunk = s.scan(/[^"\r\n]+/)
@@ -514,7 +506,7 @@ module Odin
               result << chunk
               @col += chunk.length
             else
-              # Single quote that isn't part of """
+              # Single/double quote that isn't part of closing """
               result << s.string[s.pos]
               s.pos += 1; @col += 1
             end
@@ -571,8 +563,15 @@ module Odin
           return
         end
 
+        prefix = +""
+        if !s.eos? && s.string.getbyte(s.pos) == 36 # @$ meta reference
+          prefix << "$"
+          s.pos += 1; @col += 1
+        end
+
         path = s.scan(RE_REF_PATH) || ""
         @col += path.length
+        path = prefix + path
         # Normalize leading zeros in array indices: [007] -> [7]
         path = path.gsub(/\[(\d+)\]/) { "[#{$1.to_i}]" }
         emit(TokenType::REFERENCE, path, line, col)
@@ -712,6 +711,25 @@ module Odin
         emit(TokenType::PATH, word, line, col)
       end
 
+      # Top-level metadata path: $ or $.foo (from canonical output)
+      def scan_meta_path(line, col)
+        s = @scanner
+        word = +"$"
+        s.pos += 1; @col += 1 # skip $
+        loop do
+          if (chunk = s.scan(/[a-zA-Z0-9_.\-]+/))
+            word << chunk
+            @col += chunk.length
+          elsif (idx = s.scan(RE_ARRAY_INDEX))
+            word << idx
+            @col += idx.length
+          else
+            break
+          end
+        end
+        emit(TokenType::PATH, word, line, col)
+      end
+
       def scan_identifier(line, col)
         s = @scanner
         word = +""

data/lib/odin/parsing/value_parser.rb

@@ -64,8 +64,16 @@ module Odin
             "Invalid numeric format"
           )
         end
-        val = Integer(Float(raw))
-        # Beyond JS safe integer range, store raw
+        fval = Float(raw)
+        unless fval == fval.to_i
+          raise Errors::ParseError.new(
+            Errors::ParseErrorCode::INVALID_TYPE_PREFIX,
+            token.line, token.column,
+            "Integer (##) value cannot have a fractional part: #{raw}"
+          )
+        end
+        val = fval.to_i
+        # Beyond the 2^53-1 safe integer range, store raw
         safe = val.abs <= 9_007_199_254_740_991
         Types::OdinInteger.new(val, raw: safe && raw.length <= 15 ? nil : raw)
       rescue ArgumentError
@@ -170,11 +178,8 @@ module Odin
 
       def parse_timestamp(token)
         raw = token.value
-        # Validate the date part
-        m = RE_TIMESTAMP_DATE.match(raw)
-        if m
-          validate_date!("#{m[1]}-#{m[2]}-#{m[3]}", token)
-        end
+        # Validate date portion, time components, and timezone offset
+        validate_timestamp!(raw, token)
         # DateTime.new is much faster than DateTime.parse
         # Try fast path for ISO 8601 timestamps
         dt = fast_parse_timestamp(raw) || DateTime.parse(raw)
@@ -188,6 +193,7 @@ module Odin
       end
 
       def parse_time(token)
+        validate_time!(token.value, token)
         Types::OdinTime.new(token.value)
       end
 
@@ -269,6 +275,58 @@ module Odin
         (year % 4 == 0 && year % 100 != 0) || (year % 400 == 0)
       end
 
+      RE_TIMESTAMP_FULL = /\A(\d{4}-\d{2}-\d{2})T(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?(Z|[+-]\d{2}:\d{2})?\z/.freeze
+      RE_TIME_FULL = /\AT(\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?\z/.freeze
+
+      # Validate timestamp date portion, time components, and timezone offset.
+      def validate_timestamp!(ts_str, token)
+        m = RE_TIMESTAMP_FULL.match(ts_str)
+        unless m
+          raise_temporal_error(ts_str, token)
+        end
+        validate_date!(m[1], token)
+        validate_time_components!(m[2], m[3], m[4], ts_str, token)
+        offset = m[5]
+        if offset && offset != "Z"
+          off_hour = offset[1, 2].to_i
+          off_min = offset[4, 2].to_i
+          raise_temporal_error(ts_str, token) if off_hour > 23 || off_min > 59
+        end
+      end
+
+      # Validate time-only value: THH:MM[:SS[.sss]].
+      def validate_time!(time_str, token)
+        m = RE_TIME_FULL.match(time_str)
+        unless m
+          raise_temporal_error(time_str, token)
+        end
+        validate_time_components!(m[1], m[2], m[3], time_str, token)
+      end
+
+      # Validate hour/minute/second bounds. Hour 24 only as end-of-day midnight;
+      # second may be 60 (leap second).
+      def validate_time_components!(hour_str, min_str, sec_str, raw_str, token)
+        hour = hour_str.to_i
+        minute = min_str.to_i
+        second = sec_str.nil? ? 0 : sec_str.to_i
+
+        if hour == 24
+          raise_temporal_error(raw_str, token) if minute != 0 || second != 0
+        elsif hour > 23
+          raise_temporal_error(raw_str, token)
+        end
+        raise_temporal_error(raw_str, token) if minute > 59
+        raise_temporal_error(raw_str, token) if second > 60
+      end
+
+      def raise_temporal_error(raw_str, token)
+        raise Errors::ParseError.new(
+          Errors::ParseErrorCode::UNEXPECTED_CHARACTER,
+          token.line, token.column,
+          "Invalid temporal value: #{raw_str}"
+        )
+      end
+
       def validate_base64!(data, token)
         # Check for invalid characters
         unless data.match?(/\A[A-Za-z0-9+\/]*=*\z/)

data/lib/odin/resolver/import_resolver.rb

@@ -10,7 +10,8 @@ module Odin
 
       def initialize(loader: nil)
         @loader = loader || method(:default_loader)
-        @resolved_paths = Set.new
+        @active_chain = Set.new   # paths currently being resolved (true-cycle detection)
+        @schema_cache = {}        # parsed schemas keyed by absolute path (diamond reuse)
         @total_loaded = 0
       end
 
@@ -26,6 +27,26 @@ module Odin
         flatten(schema, imported_schemas)
       end
 
+      # Resolve imports and return [flattened_schema, type_registry].
+      # base_path is the schema file path; imports resolve relative to its directory.
+      # The registry namespaces imported types by alias for @alias.typename lookup.
+      def resolve_with_registry(schema, base_path: ".")
+        import_dir = File.directory?(base_path) ? base_path : File.dirname(base_path)
+        imported_schemas = []
+        schema.imports.each do |imp|
+          resolve_import(imp, import_dir, imported_schemas, depth: 0)
+        end
+
+        registry = TypeRegistry.new
+        imported_schemas.each do |entry|
+          registry.register_all(entry[:schema].types, entry[:alias_name])
+        end
+        registry.register_all(schema.types, nil)
+
+        flattened = schema.imports.empty? ? schema : flatten(schema, imported_schemas)
+        [flattened, registry]
+      end
+
       private
 
       def resolve_import(imp, base_path, collected, depth:)
@@ -45,25 +66,32 @@ module Odin
 
         abs_path = resolve_path(base_path, imp.path)
 
-        if @resolved_paths.include?(abs_path)
+        # True cycle: path is on the current import chain.
+        if @active_chain.include?(abs_path)
           raise Errors::OdinError.new(
             Errors::ValidationErrorCode::CIRCULAR_REFERENCE,
             "Circular import detected: #{abs_path}"
           )
         end
 
-        @resolved_paths.add(abs_path)
-        @total_loaded += 1
-
-        text = @loader.call(abs_path)
-        imported_schema = Validation::SchemaParser.new.parse_schema(text)
+        imported_schema = @schema_cache[abs_path]
+        unless imported_schema
+          @total_loaded += 1
+          text = @loader.call(abs_path)
+          imported_schema = Validation::SchemaParser.new.parse_schema(text)
+          @schema_cache[abs_path] = imported_schema
+        end
 
-        # Recursively resolve nested imports
-        unless imported_schema.imports.empty?
-          import_dir = File.dirname(abs_path)
-          imported_schema.imports.each do |nested_imp|
-            resolve_import(nested_imp, import_dir, collected, depth: depth + 1)
+        @active_chain.add(abs_path)
+        begin
+          unless imported_schema.imports.empty?
+            import_dir = File.dirname(abs_path)
+            imported_schema.imports.each do |nested_imp|
+              resolve_import(nested_imp, import_dir, collected, depth: depth + 1)
+            end
           end
+        ensure
+          @active_chain.delete(abs_path)
         end
 
         collected << { schema: imported_schema, alias_name: imp.alias_name, path: abs_path }

data/lib/odin/resolver/type_registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Odin
+  module Resolver
+    # Namespaced type registry for import resolution.
+    class TypeRegistry
+      def initialize
+        @local_types = {}
+        @namespaces = {}
+      end
+
+      # Register all types from a schema under an optional namespace (import alias).
+      def register_all(types, namespace = nil)
+        if namespace
+          ns_map = (@namespaces[namespace] ||= {})
+          types.each { |name, type_def| ns_map[name] = type_def }
+        else
+          types.each { |name, type_def| @local_types[name] = type_def }
+        end
+      end
+
+      # Look up a type by name: local first, then dot-namespaced "alias.name",
+      # then any namespace for an unqualified name.
+      def lookup(name)
+        return @local_types[name] if @local_types.key?(name)
+
+        if (dot = name.index("."))
+          ns = name[0...dot]
+          type_name = name[(dot + 1)..]
+          ns_map = @namespaces[ns]
+          return ns_map[type_name] if ns_map&.key?(type_name)
+        end
+
+        @namespaces.each_value do |ns_map|
+          return ns_map[name] if ns_map.key?(name)
+        end
+        nil
+      end
+
+      def has?(name)
+        !lookup(name).nil?
+      end
+
+      # All type names, namespaced names rendered as "alias.name".
+      def all_type_names
+        names = @local_types.keys.dup
+        @namespaces.each do |ns, ns_map|
+          ns_map.each_key { |n| names << "#{ns}.#{n}" }
+        end
+        names
+      end
+    end
+  end
+end

data/lib/odin/transform/format_exporters.rb

@@ -173,57 +173,89 @@ module Odin
       # ── ODIN Export ──
 
       def self.to_odin(value, header: true, modifiers: {})
-        sb = +""
+        builder = Odin::Types::OdinDocumentBuilder.new
+        builder.set_metadata("odin", Odin::Types::OdinString.new("1.0.0")) if header
 
-        if header
-          sb << "{$}\n"
-          sb << "odin = \"1.0.0\"\n"
+        if value.object?
+          flatten_odin_paths(builder, "", value, modifiers)
+        elsif value.array?
+          flatten_odin_paths(builder, "items", value, modifiers)
+        else
+          builder.set("value", dyn_to_odin_value(value))
         end
 
-        if value.object?
-          entries = value.value
-          has_sections = entries.any? { |_k, v| v.object? || v.array? }
-
-          if has_sections
-            # Check if there are any top-level fields (non-section entries or leaf chains)
-            has_top_level = entries.any? { |_k, v| !v.object? && !v.array? } ||
-                           entries.any? { |_k, v| v.object? && pure_leaf_chain?(v) }
-
-            # Emit {} root section marker when header is present and there are top-level fields
-            sb << "{}\n" if header && has_top_level
-
-            # First pass: flat top-level fields and leaf chains
-            entries.each do |key, val|
-              if val.object?
-                collect_leaf_paths(sb, key, val, key, modifiers)
-              elsif !val.array?
-                write_assignment(sb, key, val, key, modifiers)
-              end
-            end
+        Odin.stringify(builder.build, use_headers: true)
+      end
 
-            # Second pass: sections and arrays
-            last_ctx = +""
-            entries.each do |key, val|
-              if val.object? && !pure_leaf_chain?(val)
-                write_section(sb, key, key, nil, val, modifiers, last_ctx_holder = [last_ctx])
-                last_ctx = last_ctx_holder[0]
-              elsif val.array?
-                write_array_section(sb, key, nil, val.value, modifiers)
-                last_ctx = ""
-              end
-            end
-          else
-            entries.each do |key, val|
-              write_assignment(sb, key, val, key, modifiers)
-            end
+      # Flatten a DynValue tree into path -> Odin value assignments on the builder.
+      def self.flatten_odin_paths(builder, prefix, value, modifiers)
+        if value.object?
+          value.value.each do |key, child|
+            path = prefix.empty? ? key.to_s : "#{prefix}.#{key}"
+            flatten_odin_paths(builder, path, child, modifiers)
           end
         elsif value.array?
-          sb << "items = #{format_odin_value(value)}\n"
+          value.value.each_with_index do |child, idx|
+            path = "#{prefix}[#{idx}]"
+            flatten_odin_paths(builder, path, child, modifiers)
+          end
         else
-          sb << "value = #{format_odin_value(value)}\n"
+          builder.set(prefix, dyn_to_odin_value(value), modifiers: odin_modifiers_for(prefix, modifiers))
         end
+      end
 
-        sb
+      # Build the document Modifiers for a path from tracked transform modifiers.
+      def self.odin_modifiers_for(path, modifiers)
+        return nil if modifiers.nil? || !modifiers.key?(path)
+        mods = modifiers[path]
+        return nil if mods.nil? || mods.empty?
+        Odin::Types::OdinModifiers.new(
+          required: mods.include?(:required) || mods.include?(Odin::Transform::FieldModifier::REQUIRED),
+          deprecated: mods.include?(:deprecated) || mods.include?(Odin::Transform::FieldModifier::DEPRECATED),
+          confidential: mods.include?(:confidential) || mods.include?(Odin::Transform::FieldModifier::CONFIDENTIAL)
+        )
+      end
+
+      # Convert a scalar DynValue into the corresponding Odin value, carrying
+      # ECMAScript-style numeric formatting through the raw field.
+      def self.dyn_to_odin_value(dv)
+        case dv.type
+        when :null then Odin::Types::OdinNull.new
+        when :bool then Odin::Types::OdinBoolean.new(dv.value)
+        when :integer then Odin::Types::OdinInteger.new(dv.value)
+        when :float
+          Odin::Types::OdinNumber.new(dv.value, raw: format_double_raw(dv.value))
+        when :float_raw
+          Odin::Types::OdinNumber.new(dv.value.to_f, raw: dv.value.to_s)
+        when :string then Odin::Types::OdinString.new(dv.value)
+        when :currency
+          Odin::Types::OdinCurrency.new(dv.value.to_f, currency_code: dv.currency_code,
+                                                       decimal_places: dv.decimal_places || 2)
+        when :currency_raw
+          Odin::Types::OdinCurrency.new(dv.value.to_f, currency_code: dv.currency_code,
+                                                       decimal_places: dv.decimal_places || 2, raw: dv.value.to_s)
+        when :percent
+          Odin::Types::OdinPercent.new(dv.value, raw: format_percent_raw(dv.value))
+        when :date then Odin::Types::OdinDate.new(dv.value, raw: dv.value.to_s)
+        when :timestamp then Odin::Types::OdinTimestamp.new(dv.value, raw: dv.value.to_s)
+        when :time
+          t = dv.value.to_s
+          Odin::Types::OdinTime.new(t.start_with?("T") ? t : "T#{t}")
+        when :duration then Odin::Types::OdinDuration.new(dv.value.to_s)
+        when :reference then Odin::Types::OdinReference.new(dv.value.to_s)
+        when :binary then Odin::Types::OdinBinary.new(dv.value.to_s)
+        else Odin::Types::OdinString.new(dv.value.to_s)
+        end
+      end
+
+      # ECMAScript number form: whole floats render without a fractional part.
+      def self.format_double_raw(v)
+        return v.to_i.to_s if v.finite? && v == v.to_i && v.abs < 1e15
+        format_double(v)
+      end
+
+      def self.format_percent_raw(v)
+        v == v.to_i.to_f && v.abs < 1e15 ? "#{v.to_i}.0" : v.to_s
       end
 
       # ── Flat KVP Export ──
@@ -314,13 +346,21 @@ module Odin
 
       # ── Private Helpers ──
 
+      # ECMAScript JSON.stringify form: whole-valued finite floats render as
+      # integers; others keep their numeric value.
+      def self.json_number(v)
+        return v unless v.is_a?(Float)
+        return v unless v.finite?
+        v == v.to_i && v.abs < 1e15 ? v.to_i : v
+      end
+
       def self.dynvalue_to_json_obj(dv)
         case dv.type
         when :null then nil
         when :bool then dv.value
         when :integer then dv.value
-        when :float then dv.value
-        when :float_raw then dv.value.to_f
+        when :float then json_number(dv.value)
+        when :float_raw then json_number(dv.value.to_f)
         when :string then dv.value
         when :currency
           f = dv.value.is_a?(BigDecimal) ? dv.value.to_f : dv.value.to_f
@@ -370,7 +410,7 @@ module Odin
 
       # ── ODIN formatting helpers ──
 
-      # Section writing (matches Java OdinFormatter.writeSection)
+      # Section writing
       def self.write_section(sb, full_path, display_path, parent_section, val, modifiers, last_ctx, inside_relative: false)
         entries = val.value
         return unless entries.is_a?(Hash)
@@ -414,7 +454,7 @@ module Odin
         end
       end
 
-      # Array section writing (matches Java OdinFormatter.writeArraySection)
+      # Array section writing
       def self.write_array_section(sb, name, parent_section, items, modifiers)
         prefix = parent_section ? "." : ""
 
@@ -529,7 +569,7 @@ module Odin
         result
       end
 
-      # Leaf chain detection (matches Java isPureLeafChain)
+      # Leaf chain detection
       def self.pure_leaf_chain?(val)
         return false unless val.object?
         entries = val.value
@@ -540,7 +580,7 @@ module Odin
         true
       end
 
-      # Collect leaf paths for flat nested objects (matches Java collectLeafPaths)
+      # Collect leaf paths for flat nested objects
       def self.collect_leaf_paths(sb, prefix, val, mod_path, modifiers)
         return unless pure_leaf_chain?(val)
         collect_leaf_paths_inner(sb, prefix, val, mod_path, modifiers)

data/lib/odin/transform/source_parsers.rb

@@ -336,7 +336,7 @@ module Odin
           fields["_text"] = Types::DynValue.of_string(text) unless text.empty?
         end
 
-        # Child elements — use qualified names (with namespace prefix) to match Java behavior
+        # Child elements — use qualified names (with namespace prefix)
         child_counts = Hash.new(0)
         children.each { |c| child_counts[qualified_name(c)] += 1 }
 
@@ -345,7 +345,7 @@ module Odin
           name = qualified_name(child)
           child_val = parse_xml_element(child, depth + 1)
 
-          # Elements named 'item' are always treated as arrays (matches TypeScript)
+          # Elements named 'item' are always treated as arrays
           if child_counts[name] > 1 || name == "item"
             child_arrays[name] ||= []
             child_arrays[name] << child_val