lutaml-model 0.8.16 → 0.8.18

data/lib/lutaml/key_value/transformation/value_serializer.rb

@@ -63,13 +63,26 @@ model_class: nil)
             return serialize_reference(value, rule)
           end
 
-          if nested_model?(rule)
+          if Lutaml::Model::Type::Union.rule?(rule)
+            serialize_union(value, options)
+          elsif nested_model?(rule)
             serialize_nested_model(value, rule, options)
           else
             serialize_primitive(value, rule)
           end
         end
 
+        # Union: dispatch on the value's own class (stateless). A model member
+        # serializes via its class transformation; a scalar emits as-is.
+        def serialize_union(value, options)
+          unless value.is_a?(Lutaml::Model::Serialize)
+            return Lutaml::Model::Type::Union.serialize_scalar(value, format)
+          end
+
+          transform_nested_model(value, create_transformation(value.class),
+                                 options)
+        end
+
         # Check if a value is a nested model based on the rule.
         #
         # @param rule [CompiledRule] The compiled rule

data/lib/lutaml/key_value/transformation.rb

@@ -936,9 +936,15 @@ child_mappings, options)
       def create_value_for_item(rule, value, options)
         return nil if value.nil?
 
-        # Check if this is a nested model
-        is_nested_model = rule.attribute_type.is_a?(Class) &&
-          rule.attribute_type < Lutaml::Model::Serialize
+        # Union: dispatch on the value's own class (stateless, like polymorphism).
+        # A model member serializes via its class; a scalar member emits as-is.
+        union = Lutaml::Model::Type::Union.rule?(rule)
+        is_nested_model = if union
+                            value.is_a?(Lutaml::Model::Serialize)
+                          else
+                            rule.attribute_type.is_a?(Class) &&
+                              rule.attribute_type < Lutaml::Model::Serialize
+                          end
 
         if is_nested_model
           # Validate that value matches the expected type
@@ -970,8 +976,9 @@ child_mappings, options)
           # If value is a subclass of the declared type, use its mappings instead
           # Also handle type substitution the same way
           actual_type = value.class
-          uses_polymorphism = (actual_type != rule.attribute_type &&
-            actual_type < rule.attribute_type) || uses_type_substitution
+          uses_polymorphism = union ||
+            (actual_type != rule.attribute_type &&
+              actual_type < rule.attribute_type) || uses_type_substitution
 
           # Get child transformation - may be cached or need to create
           child_transformation = rule.child_transformation
@@ -998,6 +1005,11 @@ child_mappings, options)
             # Fallback: serialize as primitive
             serialize_value(value, rule)
           end
+        elsif union
+          # Union scalar: serialize through the value type matching the value's
+          # own class so output is canonical (e.g. BigDecimal -> "1.5"), not a
+          # raw Ruby object.
+          Lutaml::Model::Type::Union.serialize_scalar(value, format)
         else
           # Serialize primitive value
           serialize_value(value, rule)

data/lib/lutaml/model/adapter_resolver.rb

@@ -231,7 +231,7 @@ module Lutaml
           end
 
           # Default key-value adapter loading
-          adapter_path = if RuntimeCompatibility.opal?
+          adapter_path = if Lutaml::Model.opal?
                            "lutaml/key_value/adapter/#{adapter}/#{type}"
                          else
                            File.join(File.dirname(__FILE__), "../key_value/adapter",
@@ -382,7 +382,7 @@ module Lutaml
         #
         # @return [Symbol, nil] :tomlib, :toml_rb, or nil
         def detect_toml_adapter
-          return nil if RuntimeCompatibility.opal?
+          return nil if Lutaml::Model.opal?
 
           if RuntimeCompatibility.windows?
             return :toml_rb if Utils.safe_load("toml-rb", :TomlRb)

data/lib/lutaml/model/attribute.rb

@@ -28,6 +28,7 @@ module Lutaml
         ref_model_class
         ref_key_attribute
         xsd_type
+        union_member_types
       ].freeze
 
       MODEL_STRINGS = [
@@ -239,6 +240,15 @@ module Lutaml
         @options[:polymorphic_class]
       end
 
+      def union?
+        unresolved_type == Lutaml::Model::Type::Union
+      end
+
+      def union_member_types
+        @union_member_types ||=
+          @options[:union_member_types].map { |member| cast_type!(member) }
+      end
+
       def derived?
         !method_name.nil?
       end
@@ -276,6 +286,43 @@ module Lutaml
         build_collection(value.map { |v| cast_element(v, register) })
       end
 
+      # Apply a value map to transform a value.
+      #
+      # value_map keys (:nil, :empty, :omitted) each map either to a symbolic
+      # option (:nil, :empty, :omitted) or, for Boolean attributes, directly
+      # to true/false. The nested form value_map[:from][key] = true/false is
+      # accepted unconditionally; the bare form value_map[key] = true/false
+      # is gated on the attribute being a Boolean type.
+      def apply_value_map(value, value_map)
+        key = if value.nil? then :nil
+              elsif Utils.empty?(value) then :empty
+              elsif Utils.uninitialized?(value) then :omitted
+              end
+        return value unless key
+
+        nested = value_map.dig(:from, key)
+        return nested if nested.is_a?(TrueClass) || nested.is_a?(FalseClass)
+
+        option = value_map[key]
+        if (option.is_a?(TrueClass) || option.is_a?(FalseClass)) &&
+            (type == Lutaml::Model::Type::Boolean ||
+             unresolved_type == Lutaml::Model::Type::Boolean)
+          return option
+        end
+
+        case option
+        when :nil
+          nil
+        when :empty
+          if key == :empty then value
+          elsif collection? then build_collection
+          else ""
+          end
+        else
+          Lutaml::Model::UninitializedClass.instance
+        end
+      end
+
       def required_value_set?(value)
         return true unless options[:required]
         return false if value.nil?
@@ -286,6 +333,7 @@ module Lutaml
 
       def cast_element(value, register)
         resolved_type = type(register)
+        return cast_union(value, nil, register) if union?
         return resolved_type.new(value) if value.is_a?(::Hash) && !hash_type?
 
         # Special handling for Reference types - pass the metadata
@@ -398,12 +446,19 @@ instance_object = nil)
         options[:values].include?(value)
       end
 
+      # Pattern binds string values only. For a plain :string attribute that is
+      # the resolved type; for a union, the pattern applies to a value that took
+      # the :string branch (a non-string member is exempt). Collections check
+      # each element, so a mix of members validates only its string entries.
       def valid_pattern!(value, resolved_type)
-        return true unless resolved_type == Lutaml::Model::Type::String
         return true unless pattern
 
-        unless pattern.match?(value)
-          raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, value)
+        Array(value).each do |item|
+          next unless resolved_type == Lutaml::Model::Type::String ||
+            item.is_a?(::String)
+          next if pattern.match?(item)
+
+          raise Lutaml::Model::PatternNotMatchedError.new(name, pattern, item)
         end
 
         true
@@ -419,11 +474,11 @@ instance_object = nil)
       #   2. Value count should be between the collection range if defined
       #      e.g if collection: 0..5 is set then the value greater then 5
       #          will raise `Lutaml::Model::CollectionCountOutOfRangeError`
-      def validate_value!(value, register, resolver = nil)
+      def validate_value!(value, register, instance_object: nil)
         # Use the default value if the value is nil
         validate_required!(value)
 
-        value = resolver&.default if value.nil?
+        value = cast_value(default_value(register, instance_object), register) if value.nil?
         resolved_type = type(register)
 
         valid_value!(value) &&
@@ -587,6 +642,8 @@ instance_object = nil)
 
         return value if already_serialized?(resolved_type, value)
 
+        return cast_union(value, format, register) if union?
+
         # Special handling for Reference types - pass the metadata
         # Check @options[:ref_model_class] which is set when type is { ref: [...] }
         if @options[:ref_model_class] && resolved_type == Lutaml::Model::Type::Reference
@@ -664,6 +721,11 @@ instance_object = nil)
 
       def process_options!
         validate_options!(@options)
+        if union?
+          @options[:union_member_types] =
+            Lutaml::Model::Type::Union.validate_members!(@options[:union_member_types])
+          Lutaml::Model::Type::Union.validate_combo!(@options)
+        end
         @raw = !!@options[:raw]
         if @raw
           warn "[DEPRECATED] attribute :#{name}, :string, raw: true is deprecated. " \
@@ -776,6 +838,13 @@ instance_object = nil)
 
       attr_writer :raw, :validations
 
+      def cast_union(value, format, register)
+        match = Lutaml::Model::Type::Union.conforming_member(
+          value, union_member_types, format: format, register: register
+        )
+        match&.last
+      end
+
       def validate_attr_type!(resolved_type)
         return true if resolved_type <= Serializable || resolved_type <= Type::Value
         return true if resolved_type.include?(Serialize)
@@ -931,12 +1000,20 @@ instance_object = nil)
                "Called from #{caller(1..1).first}"
         end
 
-        # No need to change user register#get_class, only checks if type is LutaML-Model string.
-        # Using MODEL_STRINGS since pattern is only supported for String type.
-        if options.key?(:pattern) && !MODEL_STRINGS.include?(type)
-          raise StandardError,
-                "Invalid option `pattern` given for `#{name}`, " \
-                "`pattern` is only allowed for :string type"
+        # pattern applies to string values: a plain :string attribute, or a
+        # union that includes a :string member (the pattern binds that branch).
+        # Guarded by the pattern key so non-pattern attributes never resolve
+        # their type here (custom types may be absent from the default register).
+        if options.key?(:pattern)
+          union_with_string =
+            type == Lutaml::Model::Type::Union &&
+            Array(options[:union_member_types]).intersect?(MODEL_STRINGS)
+          unless MODEL_STRINGS.include?(type) || union_with_string
+            raise StandardError,
+                  "Invalid option `pattern` given for `#{name}`, " \
+                  "`pattern` is only allowed for :string type or a union " \
+                  "including a :string member"
+          end
         end
 
         if initialize_empty? && !collection?

data/lib/lutaml/model/cached_type_resolver.rb

@@ -36,7 +36,7 @@ module Lutaml
       attr_reader :delegate, :cache_backend
 
       def self.default_cache_backend
-        if RuntimeCompatibility.opal?
+        if Lutaml::Model.opal?
           MutexHashCache.new
         else
           ConcurrentMapCache.new

data/lib/lutaml/model/choice.rb

@@ -36,6 +36,36 @@ module Lutaml
         @attributes << @model.attribute(name, type, options)
       end
 
+      # Restrict options on a predefined or imported attribute within this choice
+      #
+      # @param name [Symbol] The attribute name to restrict
+      # @param options [Hash] New options to merge
+      # @return [Symbol] The attribute name
+      def restrict(name, options = {})
+        @model.restrict(name, options)
+        attr = @model.attributes[name]
+        unless @attributes.include?(attr)
+          attr.options[:choice] = self
+          @attributes << attr
+        end
+        invalidate_cache!
+        name
+      end
+
+      # Remove an attribute from this choice block
+      #
+      # @param name [Symbol] The attribute name to remove
+      # @return [Boolean] true if the attribute was removed
+      def remove_attribute(name)
+        attr = @attributes.find { |a| !a.is_a?(Choice) && a.name == name }
+        return nil unless attr
+
+        @attributes.delete(attr)
+        attr.options.delete(:choice)
+        invalidate_cache!
+        attr
+      end
+
       def choice(min: 1, max: 1, &block)
         @attributes << Choice.new(@model, min, max, format: @format).tap do |c|
           c.instance_eval(&block)
@@ -163,6 +193,10 @@ register = nil)
 
       private
 
+      def invalidate_cache!
+        @flat_attributes = nil
+      end
+
       def raise_errors(choices_hash)
         flat_attr_names = flat_attributes.map { |attr| attr.name.to_s }
         choices_hash.each do |choice_attr, count|

data/lib/lutaml/model/compiled_rule.rb

@@ -98,6 +98,13 @@ module Lutaml
         !custom_methods.empty?
       end
 
+      # Check if form is explicitly set
+      #
+      # @return [Boolean] true if form option was provided
+      def form_set?
+        !form.nil?
+      end
+
       # Check if a name matches this rule (including alias names for multiple mappings)
       #
       # @param name [String, Symbol] The name to check

data/lib/lutaml/model/error/union_schema_unsupported_error.rb

@@ -0,0 +1,11 @@
+module Lutaml
+  module Model
+    class UnionSchemaUnsupportedError < Error
+      def initialize(attribute, format)
+        super("Union-typed attribute `#{attribute}` cannot be exported to " \
+              "#{format}; union types are only representable in JSON Schema " \
+              "(anyOf).")
+      end
+    end
+  end
+end

data/lib/lutaml/model/global_context.rb

@@ -324,10 +324,13 @@ context_id = nil)
       end
 
       class << self
-        # Performance: Define delegation methods without closures
-        # Using class_eval with string avoids closure allocation per call
+        # Block form: avoids Opal's runtime string parsing requirement
+        # (MRI's class_eval(string) needs `require 'opal-parser'` at
+        # runtime under Opal, which isn't bundled). Closures are
+        # allocated once at file load, not per call, so the perf cost
+        # over the previous string form is negligible.
 
-        class_eval <<-RUBY, __FILE__, __LINE__ + 1
+        class_eval do
           def registry
             instance.registry
           end
@@ -356,8 +359,8 @@ context_id = nil)
             instance.default_context
           end
 
-          def context(*args, **kwargs, &block)
-            instance.context(*args, **kwargs, &block)
+          def context(id = nil)
+            instance.context(id)
           end
 
           def clear_xml_namespace_registry!
@@ -404,8 +407,8 @@ context_id = nil)
             instance.resolvable?(name, ctx)
           end
 
-          def with_context(ctx_id)
-            instance.with_context(ctx_id) { yield }
+          def with_context(ctx_id, &block)
+            instance.with_context(ctx_id, &block)
           end
 
           def register_format_registry(format, registry)
@@ -440,7 +443,7 @@ context_id = nil)
           def namespace_register_map
             instance.namespace_register_map
           end
-        RUBY
+        end
       end
     end
   end

data/lib/lutaml/model/instrumentation.rb

@@ -155,7 +155,7 @@ module Lutaml
         #
         # @return [Float] the current monotonic time in seconds
         def monotonic_time
-          return Time.now.to_f if Lutaml::Model::RuntimeCompatibility.opal?
+          return Time.now.to_f if Lutaml::Model.opal?
 
           Process.clock_gettime(Process::CLOCK_MONOTONIC)
         end
@@ -164,7 +164,7 @@ module Lutaml
         #
         # @return [Integer, nil] memory in bytes, or nil if not available
         def memory_usage
-          return nil if Lutaml::Model::RuntimeCompatibility.opal?
+          return nil if Lutaml::Model.opal?
           return nil unless defined?(GC)
 
           GC.start if RUBY_VERSION >= "2.7"

data/lib/lutaml/model/mapping/mapping_rule.rb

@@ -248,12 +248,6 @@ module Lutaml
         polymorphic_map && !polymorphic_map.empty?
       end
 
-      def serialize_attribute(model, element, doc)
-        if custom_methods[:to]
-          model.public_send(custom_methods[:to], model, element, doc)
-        end
-      end
-
       def to_value_for(model)
         if delegate
           model.public_send(delegate).public_send(to)

data/lib/lutaml/model/register.rb

@@ -48,7 +48,7 @@ module Lutaml
       # Cache for resolve_for_child results.
       # Key: [child_class.object_id, parent_register] → Value: resolved register Symbol or nil.
       # Classes are singletons so object_id is stable for the process lifetime.
-      RESOLVE_CACHE = if RuntimeCompatibility.opal?
+      RESOLVE_CACHE = if Lutaml::Model.opal?
                         {}
                       else
                         Concurrent::Map.new
@@ -82,7 +82,7 @@ module Lutaml
       def self.resolve_for_child(child_class, parent_register)
         cache_key = [child_class.object_id, parent_register]
 
-        if RuntimeCompatibility.opal?
+        if Lutaml::Model.opal?
           return RESOLVE_CACHE[cache_key] if RESOLVE_CACHE.key?(cache_key)
 
           RESOLVE_CACHE[cache_key] =

data/lib/lutaml/model/runtime_compatibility.rb

@@ -91,4 +91,54 @@ if Lutaml::Model::RuntimeCompatibility.opal?
       end
     end
   end
+
+  # Opal has no `weakref` stdlib. Store uses WeakRef to let go of
+  # registered instances automatically once they go out of scope.
+  # Under Opal (browser JS GC) we substitute a strong reference —
+  # correct behavior, weaker memory profile, no API surface change.
+  unless defined?(WeakRef)
+    class ::WeakRef
+      class RefError < ::StandardError; end
+
+      def initialize(obj)
+        @__target__ = obj
+      end
+
+      def __getobj__
+        @__target__
+      end
+
+      def weakref_alive?
+        true
+      end
+
+      # Minimal method_missing so the WeakRef quacks like its target
+      # for the Store's index lookups.
+      def method_missing(name, *, &)
+        @__target__.public_send(name, *, &)
+      end
+
+      def respond_to_missing?(name, include_private = false)
+        @__target__.respond_to?(name, include_private)
+      end
+    end
+  end
+
+  # Opal's Module#prepend raises "Prepending a module multiple times
+  # is not supported" when a module is already in the target's ancestor
+  # chain. MRI's prepend is idempotent in that case (no-op, no error).
+  #
+  # Our top-level lib files (lib/lutaml/model.rb, lib/lutaml/xml.rb)
+  # can be re-evaluated under Opal's eager loader, which would trigger
+  # the raise on the second pass. Align Opal with MRI by making prepend
+  # a no-op when the module is already present.
+  class ::Module
+    unless method_defined?(:__lm_original_prepend__)
+      alias_method :__lm_original_prepend__, :prepend
+
+      def prepend(mod)
+        __lm_original_prepend__(mod) unless self <= mod
+      end
+    end
+  end
 end

data/lib/lutaml/model/schema/class_loader.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+unless RUBY_ENGINE == "opal"
+  require "fileutils"
+  require "tmpdir"
+end
+
+module Lutaml
+  module Model
+    module Schema
+      # Writes a CompiledOutput to a temporary directory, requires the
+      # registry, and runs `register_all` so the generated classes are
+      # loaded into a real module the caller can use immediately. Shared
+      # between XSD and RNG compilers.
+      class ClassLoader
+        DEFAULT_NAMESPACE = "GeneratedModels"
+
+        def self.load(output, registry_generator: RegistryGenerator)
+          new(output, registry_generator).load
+        end
+
+        def initialize(output, registry_generator)
+          # ClassLoader needs a module to host the registry constant
+          # (so `register_all` has a home). If the caller wanted
+          # unwrapped class files, we still force a registry module —
+          # but we pin `source_module_namespace` to what they asked for,
+          # so per-class files keep their original wrapping.
+          @output = CompiledOutput.new(
+            entries: output.entries,
+            module_namespace: output.module_namespace || DEFAULT_NAMESPACE,
+            register_id: output.register_id,
+            source_module_namespace: output.module_namespace,
+          )
+          @registry_generator = registry_generator
+        end
+
+        def load
+          Dir.mktmpdir do |dir|
+            FileWriter.write(@output, dir, registry_generator: @registry_generator)
+            require File.join(dir, "#{registry_basename}_registry")
+            call_register_all
+          end
+        end
+
+        private
+
+        def registry_basename
+          @output.module_namespace.split("::").last.downcase
+        end
+
+        def call_register_all
+          mod = Object.const_get(@output.module_namespace)
+          mod.register_all if mod.respond_to?(:register_all)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/compiled_output.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      # Pure value object holding the output of compilation. No I/O — just
+      # data. FileWriter / ClassLoader collaborators consume this to perform
+      # the impure parts of `to_models`. Shared across schema compilers (RNG,
+      # XSD, future formats).
+      #
+      # Entries are an ordered list of tagged records, each carrying a
+      # CamelCase class name, a payload (either a Definitions::* spec or a
+      # pre-rendered Ruby source String), and a `kind` of `:model` or
+      # `:namespace`.
+      #
+      # `:model` entries are written to disk AND registered with
+      # `register_all`. `:namespace` entries are written and autoloaded but
+      # never registered.
+      class CompiledOutput
+        Entry = Struct.new(:name, :payload, :kind)
+
+        attr_reader :entries, :module_namespace, :register_id,
+                    :source_module_namespace
+
+        # `module_namespace` is what the central registry file wraps in
+        # (and where `register_all` lives). `source_module_namespace`
+        # is what the per-class files wrap in — defaults to the same,
+        # but ClassLoader can pass a different value when the caller
+        # asked for unwrapped classes but a registry constant is still
+        # needed to drive autoload.
+        def initialize(entries:, module_namespace: nil, register_id: :default,
+                       source_module_namespace: :inherit)
+          @entries = entries
+          @module_namespace = module_namespace
+          @register_id = register_id
+          @source_module_namespace =
+            source_module_namespace == :inherit ? module_namespace : source_module_namespace
+        end
+
+        # Model-only entries — what the registry generator and ClassLoader
+        # iterate when emitting `register_all` calls.
+        def models
+          @models ||= entries.select { |e| e.kind == :model }
+        end
+
+        # Namespace-only entries — autoloaded but never registered.
+        def namespaces
+          @namespaces ||= entries.select { |e| e.kind == :namespace }
+        end
+
+        # Flat `name => Ruby source` hash covering every entry (models +
+        # namespaces). Used by FileWriter for the per-file write loop and
+        # by RNG / XSD compilers as the public `to_models` return value.
+        # Class files are rendered against `source_module_namespace`,
+        # which usually equals `module_namespace` but differs when the
+        # caller wanted unwrapped class files inside a registry module.
+        def sources
+          @sources ||= entries.to_h { |e| [e.name, source_for(e)] }
+        end
+
+        private
+
+        def source_for(entry)
+          renderer_for(entry.payload).render(
+            entry.payload,
+            module_namespace: @source_module_namespace,
+            register_id: @register_id,
+          )
+        end
+
+        def renderer_for(spec)
+          case spec
+          when Definitions::Model          then Renderers::Model
+          when Definitions::RestrictedType then Renderers::RestrictedType
+          when Definitions::UnionType      then Renderers::Union
+          when Definitions::Namespace      then Renderers::Namespace
+          else raise ArgumentError, "Unknown spec type: #{spec.class}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/definitions/attribute.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Schema
+      module Definitions
+        # One attribute on a generated class.
+        class Attribute
+          attr_accessor :name, :type, :xml_name, :kind, :collection,
+                        :default, :documentation, :initialize_empty,
+                        :render_default, :render_empty
+
+          def initialize(name:, type:, xml_name:, kind:,
+                         collection: false, default: nil,
+                         documentation: nil, initialize_empty: false,
+                         render_default: false, render_empty: false)
+            @name = name
+            @type = type
+            @xml_name = xml_name
+            @kind = kind
+            @collection = collection
+            @default = default
+            @documentation = documentation
+            @initialize_empty = initialize_empty
+            @render_default = render_default
+            @render_empty = render_empty
+          end
+        end
+      end
+    end
+  end
+end