lutaml-model 0.7.7 → 0.8.1

data/lib/lutaml/model/attribute.rb

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 module Lutaml
   module Model
     class Attribute
       attr_reader :name, :options
 
+      include CollectionHandler
+
       ALLOWED_OPTIONS = %i[
         raw
         default
@@ -13,11 +17,16 @@ module Lutaml
         transform
         choice
         sequence
+        method
         method_name
         polymorphic
         polymorphic_class
         initialize_empty
         validations
+        required
+        ref_model_class
+        ref_key_attribute
+        xsd_type
       ].freeze
 
       MODEL_STRINGS = [
@@ -26,26 +35,53 @@ module Lutaml
         :string,
       ].freeze
 
-      # Safe methods than can be overriden without any crashing
-      ALLOW_OVERRIDING = %i[
-        display
-        validate
-        hash
-        itself
-        taint
-        untaint
-        trust
-        untrust
-        methods
-        instance_variables
-        tap
-        extend
-        freeze
-        encoding
-        method
-        object_id
+      # Keys that are safe to propagate from parent to child deserialization.
+      # Parent-internal keys (namespace_uri, resolved_type, converted) are
+      # intentionally excluded — children must derive their own context.
+      CHILD_PROPAGATION_KEYS = %i[
+        lutaml_parent
+        lutaml_root
+        default_namespace
+        import_declaration_plan
+        polymorphic
+        collection
+        render_empty
+        render_nil
+        cdata
+      ].freeze
+
+      # Methods where accidental override is likely to cause issues
+      # All names are allowed - this list only controls which ones get a warning
+      # Format-specific serialization methods (to_xml, to_json, etc.) are pushed
+      # by each format plugin at load time via format_specific_warn_names.
+      WARN_ON_OVERRIDE = %i[
+        # Ruby core - overriding breaks fundamental behavior
+        hash object_id class send method
+
+        # Object lifecycle - overriding without super breaks things
+        initialize
+
+        # Serialization methods - overriding breaks serialization
+        to_format
+
+        # Internal helpers - overriding breaks internal logic
+        attr_value attribute_exist? key_exist? key_value
+        using_default? using_default_for value_set_for
+        method_missing respond_to_missing?
       ].freeze
 
+      # Format-specific warning names, appended at load time by format modules.
+      # Uses a class ivar instead of a constant since it's mutated at load time.
+      @format_specific_warn_names = []
+
+      def self.format_specific_warn_names
+        @format_specific_warn_names
+      end
+
+      def self.warn_on_override_names
+        WARN_ON_OVERRIDE + @format_specific_warn_names
+      end
+
       def self.cast_type!(type)
         case type
         when Symbol then cast_from_symbol!(type)
@@ -69,28 +105,145 @@ module Lutaml
       end
 
       def initialize(name, type, options = {})
-        validate_name!(
-          name, reserved_methods: Lutaml::Model::Serializable.instance_methods
-        )
+        skip_validation = options.fetch(:skip_validation, false)
+
+        unless skip_validation
+          validate_name!(
+            name, reserved_methods: Lutaml::Model::Serializable.instance_methods
+          )
+        end
 
         @name = name
-        @options = options
+        @options = options.except(:skip_validation)
 
-        validate_presence!(type, options[:method_name])
+        validate_presence!(type) unless skip_validation
         @type = type
-        process_options!
+        @unresolved_type = type
+        process_options! unless skip_validation
       end
 
-      def type(register_id = nil)
+      # Cache the resolver reference — GlobalContext.resolver is a singleton
+      # that never changes during the process lifetime. Avoids repeated
+      # singleton access overhead on every type() call.
+      def resolver
+        @resolver ||= GlobalContext.resolver
+      end
+
+      def type(context_or_register = nil)
         return if unresolved_type.nil?
 
-        register_id ||= Lutaml::Model::Config.default_register
-        register = Lutaml::Model::GlobalRegister.lookup(register_id)
-        register.get_class_without_register(unresolved_type)
+        # Performance: Fast path for nil or default register (most common case during deserialization)
+        if context_or_register.nil? || context_or_register == :default
+          return @cached_type_default ||= begin
+            context = normalize_context(context_or_register)
+            resolver.resolve(unresolved_type, context)
+          end
+        end
+
+        # Non-default register path: resolve directly without normalize_context
+        # when context_or_register is already a TypeContext or Symbol (common cases)
+        context = case context_or_register
+                  when Lutaml::Model::TypeContext
+                    context_or_register
+                  when Symbol
+                    GlobalContext.context(context_or_register) || GlobalContext.default_context
+                  when Lutaml::Model::Register
+                    GlobalContext.context(context_or_register.id) || GlobalContext.default_context
+                  else
+                    GlobalContext.default_context
+                  end
+
+        # Performance: Cache per TypeContext identity.
+        # When type substitution replaces a TypeContext, the object_id changes,
+        # so old cache entries are never hit again (safe invalidation).
+        cache_key = context.object_id
+        @type_cache ||= {}
+        cached = @type_cache[cache_key]
+        return cached if cached
+
+        resolved = resolver.resolve(unresolved_type, context)
+        @type_cache[cache_key] = resolved
+        resolved
+      end
+
+      # @api public
+      # Get type with namespace-aware resolution.
+      #
+      # Uses the register's resolve_in_namespace method for version-aware
+      # type resolution. Falls back to standard resolution if no namespace
+      # or register is provided.
+      #
+      # @param register [Lutaml::Model::Register, Symbol, nil] The register or register ID
+      # @param namespace_uri [String, nil] The namespace URI for version awareness
+      # @return [Class, nil] The type class or nil
+      def type_with_namespace(register, namespace_uri = nil)
+        return type(register) unless register && namespace_uri
+        return if unresolved_type.nil?
+
+        # Performance: Memoize type resolution per (register, namespace_uri) pair
+        # This avoids repeated resolve_in_namespace calls for the same attribute
+        @type_with_namespace_cache ||= {}
+        cache_key = [register, namespace_uri]
+        return @type_with_namespace_cache[cache_key] if @type_with_namespace_cache.key?(cache_key)
+
+        # Resolve register from symbol if needed
+        actual_register = if register.is_a?(Symbol)
+                            Lutaml::Model::GlobalRegister.lookup(register)
+                          else
+                            register
+                          end
+
+        # If we don't have an actual Register object, fall back to standard resolution
+        result = if actual_register.respond_to?(:resolve_in_namespace)
+                   actual_register.resolve_in_namespace(unresolved_type,
+                                                        namespace_uri)
+                 end
+        result ||= type(register)
+
+        @type_with_namespace_cache[cache_key] = result
+        result
+      end
+
+      # Extract the Register from the context_or_register argument
+      def extract_register(_context_or_register)
+        # Register backward compatibility - now always returns nil
+        # Type resolution uses GlobalContext directly
+        nil
+      end
+
+      # Normalize register/context to TypeContext for resolution
+      # Performance: Optimized to reduce allocations in hot path
+      def normalize_context(context_or_register)
+        # Fast path for nil - most common case
+        return default_type_context if context_or_register.nil?
+
+        # Fast path for TypeContext - no conversion needed
+        return context_or_register if context_or_register.is_a?(Lutaml::Model::TypeContext)
+
+        # Handle Register and Symbol cases
+        context_id = case context_or_register
+                     when Lutaml::Model::Register
+                       context_or_register.id
+                     when Symbol
+                       context_or_register
+                     else
+                       return GlobalContext.default_context
+                     end
+
+        GlobalContext.context(context_id) || GlobalContext.default_context
+      end
+
+      # Performance: Cache default type context lookup
+      def default_type_context
+        @default_type_context ||= begin
+          default_id = Lutaml::Model::Config.default_register
+          ctx = GlobalContext.context(default_id)
+          ctx || GlobalContext.default_context
+        end
       end
 
       def unresolved_type
-        @type
+        @unresolved_type || @type
       end
 
       def polymorphic?
@@ -98,15 +251,18 @@ module Lutaml
       end
 
       def derived?
-        unresolved_type.nil?
+        !method_name.nil?
       end
 
       def delegate
         @options[:delegate]
       end
 
+      # Performance: Frozen empty hash to reduce allocations
+      EMPTY_TRANSFORM_HASH = {}.freeze
+
       def transform
-        @options[:transform] || {}
+        @options[:transform] || EMPTY_TRANSFORM_HASH
       end
 
       def method_name
@@ -131,9 +287,25 @@ module Lutaml
         build_collection(value.map { |v| cast_element(v, register) })
       end
 
+      def required_value_set?(value)
+        return true unless options[:required]
+        return false if value.nil?
+        return false if value.respond_to?(:empty?) && value.empty?
+
+        true
+      end
+
       def cast_element(value, register)
         resolved_type = type(register)
-        return resolved_type.new(value) if value.is_a?(Hash) && !hash_type?
+        return resolved_type.new(value) if value.is_a?(::Hash) && !hash_type?
+
+        # Special handling for Reference types - pass the metadata
+        if unresolved_type == Lutaml::Model::Type::Reference
+          return resolved_type.cast_with_metadata(value,
+                                                  @options[:ref_model_class], @options[:ref_key_attribute])
+        end
+
+        validate_attr_type!(resolved_type)
 
         resolved_type.cast(value)
       end
@@ -146,31 +318,7 @@ module Lutaml
         :"#{@name}="
       end
 
-      def collection
-        @options[:collection]
-      end
-
-      def collection?
-        collection || false
-      end
-
-      def singular?
-        !collection?
-      end
-
-      def collection_class
-        return Array unless custom_collection?
-
-        collection
-      end
-
-      def collection_instance?(value)
-        value.is_a?(collection_class)
-      end
-
-      def build_collection(*args)
-        collection_class.new(args.flatten)
-      end
+      # Collection methods are provided by CollectionHandler module
 
       def raw?
         @raw
@@ -180,15 +328,21 @@ module Lutaml
         !enum_values.empty?
       end
 
-      def default(register = Lutaml::Model::Config.default_register)
-        cast_value(default_value(register), register)
+      def default(register = Lutaml::Model::Config.default_register,
+instance_object = nil)
+        cast_value(default_value(register, instance_object), register)
       end
 
-      def default_value(register)
+      def default_value(register, instance_object = nil)
         if delegate
-          type(register).attributes[to].default(register)
+          type(register).attributes(register)[to].default(register,
+                                                          instance_object)
         elsif options[:default].is_a?(Proc)
-          options[:default].call
+          if instance_object
+            instance_object.instance_exec(&options[:default])
+          else
+            options[:default].call
+          end
         elsif options.key?(:default)
           options[:default]
         else
@@ -196,16 +350,19 @@ module Lutaml
         end
       end
 
-      def default_set?(register)
-        !Utils.uninitialized?(default_value(register))
+      def default_set?(register, instance_object = nil)
+        !Utils.uninitialized?(default_value(register, instance_object))
       end
 
       def pattern
         options[:pattern]
       end
 
+      # Performance: Frozen empty array to reduce allocations
+      EMPTY_VALUES_ARRAY = [].freeze
+
       def enum_values
-        @options.key?(:values) ? @options[:values] : []
+        @options.key?(:values) ? @options[:values] : EMPTY_VALUES_ARRAY
       end
 
       def transform_import_method
@@ -255,9 +412,11 @@ module Lutaml
       #   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)
+      def validate_value!(value, register, resolver = nil)
         # Use the default value if the value is nil
-        value = default(register) if value.nil?
+        validate_required!(value)
+
+        value = resolver&.default if value.nil?
         resolved_type = type(register)
 
         valid_value!(value) &&
@@ -273,7 +432,8 @@ module Lutaml
         return true if Utils.blank?(value)
 
         memoization_container = {}
-        errors = Lutaml::Model::Validator.call(value, validations, memoization_container)
+        errors = Lutaml::Model::Validator.call(value, validations,
+                                               memoization_container)
 
         return if errors.empty?
 
@@ -281,7 +441,11 @@ module Lutaml
       end
 
       def validate_polymorphic(value, resolved_type)
-        return value.all? { |v| validate_polymorphic!(v, resolved_type) } if value.is_a?(Array)
+        if value.is_a?(Array)
+          return value.all? do |v|
+            validate_polymorphic!(v, resolved_type)
+          end
+        end
         return true unless options[:polymorphic]
 
         valid_polymorphic_type?(value, resolved_type)
@@ -325,37 +489,39 @@ module Lutaml
       end
 
       def valid_collection!(value, caller)
-        raise Lutaml::Model::CollectionTrueMissingError.new(name, caller) if collection_instance?(value) && !collection?
+        if collection_instance?(value) && !collection?
+          raise Lutaml::Model::CollectionTrueMissingError.new(name,
+                                                              caller)
+        end
 
         return true unless collection?
 
         # Allow any value for unbounded collections
-        return true if options[:collection] == true
+        return true if collection == true
 
-        unless collection_instance?(value)
+        unless (Utils.uninitialized?(value) && resolved_collection.min.zero?) || collection_instance?(value)
           raise Lutaml::Model::CollectionCountOutOfRangeError.new(
             name,
             value,
-            options[:collection],
+            collection,
           )
         end
 
-        range = options[:collection]
-        return true unless range.is_a?(Range)
+        return true unless resolved_collection.is_a?(Range)
 
-        if range.is_a?(Range) && range.end.nil?
-          if value.size < range.begin
+        if resolved_collection.is_a?(Range) && resolved_collection.end.infinite?
+          if value.size < resolved_collection.begin
             raise Lutaml::Model::CollectionCountOutOfRangeError.new(
               name,
               value,
-              range,
+              collection,
             )
           end
-        elsif range.is_a?(Range) && !range.cover?(value.size)
+        elsif resolved_collection.is_a?(Range) && !resolved_collection.cover?(value.size)
           raise Lutaml::Model::CollectionCountOutOfRangeError.new(
             name,
             value,
-            range,
+            collection,
           )
         end
       end
@@ -363,25 +529,80 @@ module Lutaml
       def serialize(value, format, register, options = {})
         value ||= build_collection if collection? && initialize_empty?
         return value if value.nil? || Utils.uninitialized?(value)
-        return value if derived?
 
         resolved_type = options[:resolved_type] || type(register)
         serialize_options = options.merge(resolved_type: resolved_type)
-        return serialize_array(value, format, register, serialize_options) if collection_instance?(value)
-        return serialize_model(value, format, register, options) if resolved_type <= Serialize
+        value = reference_key(value) if unresolved_type == Lutaml::Model::Type::Reference
+        if collection_instance?(value)
+          return serialize_array(value, format, register,
+                                 serialize_options)
+        end
+        if resolved_type <= Serialize
+          return serialize_model(value, format, register,
+                                 options)
+        end
 
         serialize_value(value, format, resolved_type)
       end
 
+      def reference_key(value)
+        return nil unless value
+        return value.map { |item| reference_key(item) } if value.is_a?(Array)
+
+        return value.public_send(@options[:ref_key_attribute]) if model_instance?(value)
+
+        value
+      end
+
+      def model_instance?(value)
+        return false unless value.respond_to?(:class)
+        return false unless @options[:ref_model_class]
+
+        value.class.name == @options[:ref_model_class]
+      end
+
       def cast(value, format, register, options = {})
-        resolved_type = options[:resolved_type] || type(register)
-        return build_collection(value.map { |v| cast(v, format, register, options.merge(resolved_type: resolved_type)) }) if collection_instance?(value) || value.is_a?(Array)
+        # Namespace-aware type resolution: use type_with_namespace if namespace_uri provided
+        namespace_uri = options[:namespace_uri]
+        resolved_type = if options[:resolved_type]
+                          options[:resolved_type]
+                        elsif register && namespace_uri
+                          type_with_namespace(register, namespace_uri)
+                        else
+                          type(register)
+                        end
+        if collection_instance?(value) || value.is_a?(Array)
+          return build_collection(value.map do |v|
+            cast(v, format, register,
+                 options.merge(resolved_type: resolved_type, converted: true))
+          end)
+        end
 
         return value if already_serialized?(resolved_type, value)
 
+        # 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
+          return resolved_type.cast_with_metadata(value,
+                                                  @options[:ref_model_class], @options[:ref_key_attribute])
+        end
+
+        # Fast path for Type::Value subclasses (String, Integer, Boolean, etc.)
+        # These are never Serializable, so skip expensive can_serialize? and needs_conversion? checks
+        # Skip if type has custom from_xml/from_json methods (defined on the class itself, not inherited)
+        if resolved_type.is_a?(Class) && resolved_type < Lutaml::Model::Type::Value
+          has_custom_from_xml = resolved_type.respond_to?(:from_xml) &&
+            resolved_type.method(:from_xml).owner != Lutaml::Model::Type::Value
+          has_custom_from_json = resolved_type.respond_to?(:from_json) &&
+            resolved_type.method(:from_json).owner != Lutaml::Model::Type::Value
+          return resolved_type.cast(value) unless has_custom_from_xml || has_custom_from_json
+        end
+
         klass = resolve_polymorphic_class(resolved_type, value, options)
-        if can_serialize?(klass, value, format)
-          klass.apply_mappings(value, format, options.merge(register: register))
+        if can_serialize?(klass, value, format, options)
+          propagated = options.slice(*CHILD_PROPAGATION_KEYS)
+          klass.apply_mappings(value, format,
+                               propagated.merge(register: register))
         elsif needs_conversion?(klass, value)
           klass.send(:"from_#{format}", value)
         else
@@ -395,24 +616,47 @@ module Lutaml
         type(register) <= Serialize
       end
 
-      def collection_range
-        return unless collection?
+      # Cached version of serializable? check for hot deserialization path
+      # Called millions of times in resolve_rule_names_with_type and value_for_rule
+      def serializable_type?(register = nil)
+        register_key = register || :default
+        return @serializable_type_cache[register_key] if defined?(@serializable_type_cache) && @serializable_type_cache&.key?(register_key)
 
-        collection.is_a?(Range) ? collection : 0..Float::INFINITY
+        resolved_type = type(register_key)
+        result = resolved_type.is_a?(Class) && resolved_type.include?(Serialize)
+        @serializable_type_cache ||= {}
+        @serializable_type_cache[register_key] = result
       end
 
+      # resolved_collection is provided by CollectionHandler module
+
       def sequenced_appearance_count(element_order, mapped_name, current_index)
         elements = element_order[current_index..]
-        element_count = elements.take_while { |element| element == mapped_name }.count
-        return element_count if element_count.between?(*collection_range.minmax)
+        element_count = elements.take_while do |element|
+          element == mapped_name
+        end.count
+        return element_count if element_count.between?(*resolved_collection.minmax)
 
         raise Lutaml::Model::ElementCountOutOfRangeError.new(
           mapped_name,
           element_count,
-          collection_range,
+          collection,
         )
       end
 
+      def validate_choice_content!(elements)
+        return elements.count unless resolved_collection
+        return 1 if elements.count.between?(*resolved_collection.minmax)
+
+        elements.each_slice(resolved_collection.max).count
+      end
+
+      # min_collection_zero? is provided by CollectionHandler module
+
+      def choice
+        @options[:choice]
+      end
+
       def process_options!
         validate_options!(@options)
         @raw = !!@options[:raw]
@@ -421,23 +665,126 @@ module Lutaml
       end
 
       def deep_dup
-        self.class.new(name, unresolved_type, Utils.deep_dup(options))
+        # Don't deep_dup the entire options hash because:
+        # 1. Lambdas/Procs (like :default) should not be duplicated
+        # 2. Classes (like :collection class) are immutable
+        # 3. Deep dupping creates circular references when lambdas close over the attribute
+
+        # Selectively copy options using direct type checks to avoid method calls
+        duped_options = { skip_validation: true }
+        options.each do |key, value|
+          duped_options[key] = case value
+                               when Symbol, TrueClass, FalseClass, Numeric, Class, Module, Proc, Method, NilClass
+                                 value # Immutable, don't dup
+                               when Range
+                                 # Only dup if bounds are mutable strings
+                                 if value.begin.is_a?(String) || (value.end && value.end.is_a?(String))
+                                   Range.new(value.begin.dup, value.end&.dup, value.exclude_end?)
+                                 else
+                                   value # Immutable bounds, safe to reuse
+                                 end
+                               when Hash
+                                 Utils.deep_dup(value)
+                               when Array
+                                 Utils.deep_dup(value)
+                               else
+                                 value # Keep as-is (might be a complex object)
+                               end
+        end
+
+        # Skip validation during deep_dup - options are already validated in original
+        # This prevents infinite recursion when process_options! tries to access collection
+        self.class.new(name, unresolved_type, duped_options).tap do |dup_attr|
+          # Copy already-processed instance variables directly
+          dup_attr.send(:raw=, @raw)
+          dup_attr.send(:validations=, @validations)
+        end
+      end
+
+      # @api public
+      # Get namespace class from Type::Value or Model class
+      #
+      # @param register [Symbol, nil] register ID for type resolution
+      # @return [Class, nil] XmlNamespace class if type has namespace
+      def type_namespace_class(register = nil)
+        register_key = register || :default
+        return @type_ns_class_cache[register_key] if defined?(@type_ns_class_cache) && @type_ns_class_cache&.key?(register_key)
+
+        # Resolve type namespace via type() which uses GlobalContext.resolver
+        resolved_type = type(register_key)
+        result = nil
+
+        # Check if type is a Type::Value class
+        # Type namespaces are ONLY declared on Type::Value subclasses,
+        # not on Serializable models. Serializable models have element
+        # namespaces, which are handled separately.
+        if resolved_type.is_a?(Class) && resolved_type <= Lutaml::Model::Type::Value
+          result = resolved_type.namespace_class
+        end
+
+        @type_ns_class_cache ||= {}
+        @type_ns_class_cache[register_key] = result
+      end
+
+      # @api public
+      # Get namespace URI from type
+      #
+      # @param register [Symbol, nil] register ID for type resolution
+      # @return [String, nil] namespace URI
+      def type_namespace_uri(register = nil)
+        register_key = register || :default
+        return @type_ns_uri_cache[register_key] if defined?(@type_ns_uri_cache) && @type_ns_uri_cache&.key?(register_key)
+
+        result = type_namespace_class(register_key)&.uri
+        @type_ns_uri_cache ||= {}
+        @type_ns_uri_cache[register_key] = result
+      end
+
+      # @api public
+      # Get namespace prefix from type
+      #
+      # @param register [Symbol, nil] register ID for type resolution
+      # @return [String, nil] namespace prefix
+      def type_namespace_prefix(register = nil)
+        type_namespace_class(register)&.prefix_default
       end
 
       private
 
+      attr_writer :raw, :validations
+
+      def validate_attr_type!(resolved_type)
+        return true if resolved_type <= Serializable || resolved_type <= Type::Value
+        return true if resolved_type.include?(Serialize)
+
+        raise Lutaml::Model::InvalidAttributeTypeError.new(name,
+                                                           resolved_type.name)
+      end
+
+      # validated_range_object is provided by CollectionHandler module
+
       def validate_name!(name, reserved_methods:)
+        # No errors - all names are allowed
+        # Only warn for methods where accidental override is problematic
         return unless reserved_methods.include?(name.to_sym)
+        return unless self.class.warn_on_override_names.include?(name.to_sym)
 
-        if ALLOW_OVERRIDING.include?(name.to_sym)
-          warn_name_conflict(name)
-        else
-          raise Lutaml::Model::InvalidAttributeNameError.new(name)
-        end
+        warn_name_conflict(name)
       end
 
       def warn_name_conflict(name)
-        Logger.warn("Attribute name `#{name}` conflicts with a built-in method")
+        # Find the first caller location outside the lutaml-model gem's lib directory
+        # This ensures we report the user's code line, not internal gem code
+        gem_lib_dir = File.expand_path("../..", __dir__)
+        location = caller_locations.find do |cl|
+          !cl.absolute_path.to_s.start_with?(gem_lib_dir)
+        end
+
+        Logger.warn(
+          "Attribute `#{name}` overrides a method. " \
+          "Ensure you call `super` if needed, or consider renaming.",
+          location || caller_locations(1..1).first,
+        )
       end
 
       def resolve_polymorphic_class(type, value, options)
@@ -456,22 +803,18 @@ module Lutaml
       end
 
       def castable?(value, format)
-        value.is_a?(Hash) ||
-          (format == :xml && value.is_a?(Lutaml::Model::Xml::XmlElement))
+        value.is_a?(::Hash) ||
+          ((castable_type = FormatRegistry.castable_type_for(format)) && value.is_a?(castable_type))
       end
 
-      def can_serialize?(klass, value, format)
-        klass <= Serialize && castable?(value, format)
-      end
-
-      def custom_collection?
-        return false if singular?
-        return false if collection == true
-        return false if collection.is_a?(Range)
+      def can_serialize?(klass, value, format, options)
+        return false unless klass <= Serialize
 
-        collection <= Lutaml::Model::Collection
+        castable?(value, format) || options[:converted]
       end
 
+      # custom_collection? is provided by CollectionHandler module
+
       def needs_conversion?(klass, value)
         !value.nil? && !value.is_a?(klass) && Utils.initialized?(value)
       end
@@ -485,34 +828,84 @@ module Lutaml
       end
 
       def serialize_model(value, format, register, options)
-        as_options = options.merge(register: register)
-        return unless Utils.present?(value)
+        # Use the value's own lutaml_register if available (proper OOP - model carries its context)
+        # This ensures child models serialize using their native context, not the parent's
+        value_register = if value.is_a?(Lutaml::Model::Serializable) && value.lutaml_register
+                           value.lutaml_register
+                         else
+                           register
+                         end
+
+        as_options = options.slice(*CHILD_PROPAGATION_KEYS).merge(register: value_register)
+
+        # Respect mapping layer policy: render_empty from MappingRule
+        # Allow empty Serializable models when render_empty: true
+        render_empty = options[:render_empty]
+        if render_empty && value.is_a?(Lutaml::Model::Serializable)
+          # Mapping layer says render this empty model - bypass present check
+        else
+          return unless Utils.present?(value)
+        end
 
         resolved_type = as_options.delete(:resolved_type) || type(register)
-        return value.class.as(format, value, as_options) if value.is_a?(resolved_type)
+        if value.is_a?(resolved_type)
+          return value.class.as(format, value,
+                                as_options)
+        end
 
         resolved_type.as(format, value, as_options)
       end
 
       def serialize_value(value, format, resolved_type)
-        value = resolved_type.new(value) unless value.is_a?(Type::Value)
+        value = wrap_in_type_if_needed(value, resolved_type)
         value.send(:"to_#{format}")
       end
 
-      def validate_presence!(type, method_name)
-        return if type || method_name
+      def wrap_in_type_if_needed(value, resolved_type)
+        return value if value.is_a?(Type::Value)
+
+        if resolved_type == Type::Reference
+          create_reference_instance(resolved_type, value)
+        else
+          resolved_type.new(value)
+        end
+      end
 
-        raise ArgumentError, "method or type must be set for an attribute"
+      def create_reference_instance(resolved_type, key = nil)
+        resolved_type.new(@options[:ref_model_class],
+                          @options[:ref_key_attribute], key)
+      end
+
+      def validate_presence!(type)
+        return if type
+
+        raise ArgumentError, "type must be set for an attribute"
+      end
+
+      def validate_required!(value)
+        return if required_value_set?(value)
+
+        raise Lutaml::Model::RequiredAttributeMissingError.new(name)
       end
 
       def set_default_for_collection
         validate_collection_range
-        @options[:default] ||= -> { build_collection } if initialize_empty?
+        attr = self
+        @options[:default] ||= -> { attr.build_collection } if initialize_empty?
       end
 
       def validate_options!(options)
         if (invalid_opts = options.keys - ALLOWED_OPTIONS).any?
-          raise Lutaml::Model::InvalidAttributeOptionsError.new(name, invalid_opts)
+          raise Lutaml::Model::InvalidAttributeOptionsError.new(name,
+                                                                invalid_opts)
+        end
+
+        # Deprecation warning for :xsd_type attribute option
+        if options.key?(:xsd_type)
+          warn "[DEPRECATION] The :xsd_type attribute option is deprecated and will be removed in v1.0.0. " \
+               "Create a custom Type::Value class with xsd_type at class level instead. " \
+               "See: docs/migration-guides/xsd-type-migration.adoc " \
+               "Called from #{caller(1..1).first}"
         end
 
         # No need to change user register#get_class, only checks if type is LutaML-Model string.
@@ -531,7 +924,8 @@ module Lutaml
       end
 
       def validate_type!(type)
-        return true if [Symbol, String].include?(type.class) || type.is_a?(Class)
+        return true if [Symbol,
+                        String].include?(type.class) || type.is_a?(Class)
 
         raise ArgumentError,
               "Invalid type: #{type}, must be a Symbol, String or a Class"