lutaml-model 0.7.6 → 0.8.0

data/lib/lutaml/xml/type/serializers.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Type
+      # Registers XML-specific type serializers for all types that need
+      # custom to_xml / from_xml behavior beyond the default (return value).
+      module Serializers
+        module_function
+
+        def register_all!
+          v = Lutaml::Model::Type::Value
+
+          # String — value&.to_s
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::String,
+            to: ->(inst) { inst.value&.to_s },
+            from: ->(val) { Lutaml::Model::Type::String.cast(val) }
+          )
+
+          # Float — value.to_s
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Float,
+            to: ->(inst) { inst.value.to_s }
+          )
+
+          # Boolean — value.to_s
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Boolean,
+            to: ->(inst) { inst.value.to_s }
+          )
+
+          # Time — ISO8601 with fractional seconds handling
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Time,
+            to: lambda { |inst|
+              return nil unless inst.value
+
+              if inst.value.subsec.zero?
+                inst.value.iso8601
+              else
+                inst.value.iso8601(6).sub(/(\.\d{3})0{3}([+-])/, '\1\2')
+              end
+            }
+          )
+
+          # DateTime — ISO8601 with Z for UTC
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::DateTime,
+            to: lambda { |inst|
+              return nil unless inst.value
+
+              result = Lutaml::Model::Type::DateTime.format_datetime_iso8601(inst.value)
+              inst.value.offset.zero? ? result.sub(/\+00:00$/, "Z") : result
+            }
+          )
+
+          # Date — ISO8601 with Z for UTC
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Date,
+            to: lambda { |inst|
+              return nil unless inst.value
+
+              result = Lutaml::Model::Type::Date.serialize(inst.value)
+              result = result.sub(/\+00:00$/, "Z") if result.include?("+00:00")
+              result
+            }
+          )
+
+          # TimeWithoutDate — delegates to self.class.serialize
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::TimeWithoutDate,
+            to: ->(inst) { Lutaml::Model::Type::TimeWithoutDate.serialize(inst.value) }
+          )
+
+          # Symbol — :symbol: format
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Symbol,
+            to: ->(inst) { ":#{inst.value}:" }
+          )
+
+          # Hash — value (pass-through)
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Hash,
+            to: lambda(&:value)
+          )
+
+          # Reference — key&.to_s
+          v.register_format_type_serializer(
+            :xml, Lutaml::Model::Type::Reference,
+            to: ->(inst) { inst.key&.to_s },
+            from: ->(val) { Lutaml::Model::Type::Reference.cast(val) }
+          )
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type/value_xml_mapping.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module Type
+      # XML mapping configuration for Type::Value classes
+      #
+      # This class holds the XML configuration for value types,
+      # including namespace and XSD type information.
+      #
+      # @example Creating a custom XML mapping
+      #   mapping = ValueXmlMapping.new
+      #   mapping.namespace(MyNamespace)
+      #   mapping.xsd_type(:string)
+      #
+      class ValueXmlMapping
+        include Lutaml::Xml::SharedDsl
+
+        attr_accessor :namespace_class, :xsd_type_name
+
+        def initialize
+          @namespace_class = nil
+          @xsd_type_name = nil
+        end
+
+        # Set the namespace for this Value type
+        #
+        # @param ns_class_or_symbol [Class, Symbol] XmlNamespace class, :blank, or :inherit
+        # @return [void]
+        #
+        # @raise [Lutaml::Xml::Error::InvalidNamespaceError] if invalid namespace class provided
+        #
+        # @example Setting namespace with XmlNamespace class
+        #   mapping.namespace(MyNamespace)
+        #
+        # @example Setting blank namespace
+        #   mapping.namespace(:blank)
+        #
+        # @example Inheriting parent namespace
+        #   mapping.namespace(:inherit)
+        def namespace(ns_class_or_symbol)
+          validate_namespace_class!(ns_class_or_symbol)
+          @namespace_class = ns_class_or_symbol
+        end
+
+        # Get the namespace URI for this mapping
+        #
+        # @return [String, nil] the namespace URI
+        def namespace_uri
+          @namespace_class&.uri
+        end
+
+        # Get the namespace prefix for this mapping
+        #
+        # @return [String, nil] the namespace prefix
+        def namespace_prefix
+          @namespace_class&.prefix_default
+        end
+
+        # Set the XSD type name
+        #
+        # @param type [Symbol, Class] XSD type symbol or Type class
+        # @return [void]
+        #
+        # @example Setting XSD type with Symbol
+        #   mapping.xsd_type(:string)  # becomes 'xs:string'
+        #
+        # @example Setting XSD type with Type class
+        #   mapping.xsd_type(Lutaml::Model::Type::String)
+        def xsd_type(type)
+          @xsd_type_name = resolve_xsd_type(type)
+        end
+
+        # Create a deep duplicate of this mapping
+        #
+        # Used for inheritance when a child type needs its own copy
+        # of the parent's XML configuration.
+        #
+        # @return [ValueXmlMapping] a new mapping with copied values
+
+        def deep_dup
+          self.class.new.tap do |dup|
+            # namespace_class is a class reference, no need to deep copy
+            dup.namespace_class = @namespace_class
+            # xsd_type_name is a string, duplicate for safety
+            if @xsd_type_name
+              dup.xsd_type_name = @xsd_type_name.dup
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace/collector.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      # Collects type namespace references from a model
+      #
+      # Type namespaces are namespaces declared on attribute types via
+      # xml_namespace directive. They are collected separately from element
+      # namespaces because they have different scoping rules.
+      class Collector
+        attr_reader :register
+
+        def initialize(register = nil)
+          @register = register || Lutaml::Model::Config.default_register
+        end
+
+        # Collect type namespace references from a single attribute
+        #
+        # @param attribute [Attribute] The attribute definition
+        # @param rule [MappingRule] The mapping rule
+        # @param context [Symbol] :attribute or :element
+        # @return [Reference, nil] The type namespace reference, or nil
+        def collect_from_attribute(attribute, rule, context)
+          return nil if rule.namespace_set?
+          return nil unless attribute
+
+          # Create reference (lazy resolution of actual namespace)
+          Reference.new(attribute, rule, context)
+        end
+
+        # Collect all type namespace references from a mapping
+        #
+        # @param mapping [Xml::Mapping] The XML mapping
+        # @param mapper_class [Class] The model class
+        # @return [Array<Reference>] Array of type namespace references
+        def collect_from_mapping(mapping, mapper_class)
+          references = []
+
+          return references unless mapper_class.is_a?(Class) &&
+            mapper_class.include?(Lutaml::Model::Serialize)
+
+          attributes = mapper_class.attributes
+
+          # Collect from attribute rules
+          mapping.attributes.each do |attr_rule|
+            next unless attr_rule.attribute?
+            next if attr_rule.to.nil?
+
+            attr_def = attributes[attr_rule.to]
+            next unless attr_def
+
+            # Only collect if rule doesn't explicitly set namespace
+            next if attr_rule.namespace_set?
+
+            ref = collect_from_attribute(attr_def, attr_rule, :attribute)
+            references << ref if ref
+          end
+
+          # Collect from element rules
+          mapping.elements.each do |elem_rule|
+            attr_def = attributes[elem_rule.to]
+            next unless attr_def
+
+            # Only collect if rule doesn't explicitly set namespace
+            next if elem_rule.namespace_set?
+
+            ref = collect_from_attribute(attr_def, elem_rule, :element)
+            references << ref if ref
+          end
+
+          references
+        end
+
+        # Resolve type namespace references to namespace classes
+        #
+        # @param references [Array<Reference>] The type namespace references
+        # @return [Hash<Symbol, Class>] Hash of context => Set of namespace classes
+        def resolve_references(references)
+          result = {
+            attributes: Set.new,
+            elements: Set.new,
+          }
+
+          references.each do |ref|
+            ns_class = ref.namespace_class(@register)
+            next unless ns_class
+
+            if ref.attribute_context?
+              result[:attributes] << ns_class
+            else
+              result[:elements] << ns_class
+            end
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace/declaration.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      # Value object representing a type namespace declaration
+      #
+      # Type namespaces are declared on PARENT elements and used by
+      # CHILD elements as prefixes.
+      class Declaration
+        VALID_DECLARED_AT_VALUES = %i[root parent inline].freeze
+
+        attr_reader :namespace_class, :prefix, :declared_at, :element_name
+
+        # @param namespace_class [XmlNamespace] The namespace class
+        # @param prefix [String] The prefix to use
+        # @param declared_at [Symbol] :root, :parent, or :inline
+        # @param element_name [String, nil] The element name (for debugging)
+        def initialize(namespace_class:, prefix:, declared_at:,
+    element_name: nil)
+          unless VALID_DECLARED_AT_VALUES.include?(declared_at)
+            raise ArgumentError,
+                  "declared_at must be :root, :parent, or :inline, got: #{declared_at.inspect}"
+          end
+
+          @namespace_class = namespace_class
+          @prefix = prefix
+          @declared_at = declared_at
+          @element_name = element_name
+          freeze
+        end
+
+        # Check if declared at root
+        def root_level?
+          @declared_at == :root
+        end
+
+        # Check if declared at parent
+        def parent_level?
+          @declared_at == :parent
+        end
+
+        # Check if declared inline
+        def inline?
+          @declared_at == :inline
+        end
+
+        # Get the xmlns attribute string
+        #
+        # @return [String] The xmlns declaration (e.g., "xmlns:dc=...")
+        def to_xmlns_attribute
+          "xmlns:#{@prefix}=#{@namespace_class.uri}"
+        end
+
+        def to_s
+          "TypeNamespaceDeclaration: #{@prefix}=#{@namespace_class.uri} (#{@declared_at})"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace/planner.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      # Plans type namespace declarations for elements
+      #
+      # Type namespaces are declared on PARENT elements and used by
+      # CHILD elements as prefixes. This planner determines where
+      # to declare each type namespace.
+      class Planner
+        attr_reader :collector, :resolver
+
+        def initialize(register = nil)
+          @collector = Collector.new(register)
+          @resolver = Resolver.new
+        end
+
+        # Plan type namespace declarations for an element
+        #
+        # @param mapping [Xml::Mapping] The XML mapping
+        # @param mapper_class [Class] The model class
+        # @param element_namespace_class [XmlNamespace, nil] Element's namespace
+        # @param existing_declarations [Hash] Already declared namespaces {prefix => uri}
+        # @return [Array<Declaration>] Array of type namespace declarations
+        def plan_for_element(mapping, mapper_class, element_namespace_class,
+    existing_declarations = {})
+          # Collect type namespace references
+          references = @collector.collect_from_mapping(mapping, mapper_class)
+
+          # Resolve to namespace classes
+          resolved = @collector.resolve_references(references)
+
+          # Build declarations
+          declarations = []
+
+          # Process attribute type namespaces
+          resolved[:attributes].each do |ns_class|
+            next if already_declared?(ns_class, existing_declarations)
+            next unless @resolver.needs_declaration?(ns_class,
+                                                     element_namespace_class)
+
+            prefix = ns_class.prefix_default || generate_prefix("attr",
+                                                                existing_declarations)
+
+            declarations << Declaration.new(
+              namespace_class: ns_class,
+              prefix: prefix,
+              declared_at: :parent,
+              element_name: mapping&.root_element,
+            )
+          end
+
+          # Process element type namespaces
+          resolved[:elements].each do |ns_class|
+            next if already_declared?(ns_class, existing_declarations)
+            next unless @resolver.needs_declaration?(ns_class,
+                                                     element_namespace_class)
+
+            prefix = ns_class.prefix_default || generate_prefix("elem",
+                                                                existing_declarations)
+
+            declarations << Declaration.new(
+              namespace_class: ns_class,
+              prefix: prefix,
+              declared_at: :parent,
+              element_name: mapping&.root_element,
+            )
+          end
+
+          declarations
+        end
+
+        # Plan type namespace declarations for root element
+        #
+        # @param mapping [Xml::Mapping] The XML mapping
+        # @param mapper_class [Class] The model class
+        # @param element_namespace_class [XmlNamespace, nil] Root's namespace
+        # @return [Array<Declaration>] Array of type namespace declarations
+        def plan_for_root(mapping, mapper_class, element_namespace_class)
+          plan_for_element(mapping, mapper_class,
+                           element_namespace_class).map do |decl|
+            # Convert to root-level declarations
+            Declaration.new(
+              namespace_class: decl.namespace_class,
+              prefix: decl.prefix,
+              declared_at: :root,
+              element_name: decl.element_name,
+            )
+          end
+        end
+
+        private
+
+        # Check if namespace is already declared
+        #
+        # @param ns_class [XmlNamespace] The namespace class
+        # @param existing [Hash] Existing declarations {prefix => uri}
+        # @return [Boolean] true if already declared
+        def already_declared?(ns_class, existing)
+          existing.value?(ns_class.uri)
+        end
+
+        # Generate a unique prefix
+        #
+        # @param base [String] Base prefix (e.g., "attr", "elem")
+        # @param existing [Hash] Existing declarations {prefix => uri}
+        # @return [String] A unique prefix
+        def generate_prefix(base, existing)
+          counter = 0
+          loop do
+            prefix = counter.zero? ? "tn#{base}" : "tn#{base}#{counter}"
+            return prefix unless existing.key?(prefix)
+
+            counter += 1
+          end
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace/reference.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      # Value object representing a reference to a type namespace
+      #
+      # Type namespaces are declared on attribute types via xml_namespace.
+      # This reference tracks the attribute, rule, and context for later resolution.
+      class Reference
+        attr_reader :attribute, :rule, :context, :mapper_class
+
+        # @param attribute [Attribute] The attribute definition
+        # @param rule [MappingRule] The mapping rule
+        # @param context [Symbol] :attribute or :element
+        # @param mapper_class [Class, nil] The model class that owns this attribute
+        def initialize(attribute, rule, context, mapper_class: nil)
+          unless %i[
+            attribute element
+          ].include?(context)
+            raise ArgumentError,
+                  "Context must be :attribute or :element"
+          end
+
+          @attribute = attribute
+          @rule = rule
+          @context = context
+          @mapper_class = mapper_class
+          freeze
+        end
+
+        # Get the type class from the attribute, resolving the register context
+        # from the mapper_class if available.
+        #
+        # @param register [Object] The type register
+        # @return [Class, nil] The type class
+        def type_class(register)
+          resolved = if @mapper_class
+                       Lutaml::Model::Register.resolve_for_child(@mapper_class,
+                                                                 register)
+                     else
+                       register
+                     end
+          @attribute.type(resolved)
+        end
+
+        # Get the namespace class from the type, resolving the register context
+        # from the mapper_class if available.
+        #
+        # @param register [Object] The type register
+        # @return [XmlNamespace, nil] The namespace class
+        def namespace_class(register)
+          type = type_class(register)
+          return nil unless type.is_a?(Class) && type <= Lutaml::Model::Type::Value
+
+          type.namespace_class
+        end
+
+        # Check if this is for an attribute context
+        def attribute_context?
+          @context == :attribute
+        end
+
+        # Check if this is for an element context
+        def element_context?
+          @context == :element
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace/resolver.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      # Resolves type namespace prefixes for elements
+      #
+      # Type namespaces are declared on parent elements and used as
+      # prefixes on child elements. This resolver determines which
+      # prefix to use for a given type namespace.
+      class Resolver
+        # Get the prefix for a type namespace on an element
+        #
+        # @param type_namespace_class [XmlNamespace] The type namespace class
+        # @param declaration_plan [DeclarationPlan] The declaration plan
+        # @return [String, nil] The prefix, or nil if not declared
+        def prefix_for(type_namespace_class, declaration_plan)
+          return nil unless type_namespace_class
+          return nil unless declaration_plan
+
+          # Look up namespace in plan
+          ns_info = declaration_plan.namespace_for_class(type_namespace_class)
+          return nil unless ns_info
+
+          # Return the prefix
+          ns_info[:prefix]
+        end
+
+        # Check if a type namespace needs to be declared
+        #
+        # @param type_namespace_class [XmlNamespace] The type namespace class
+        # @param element_namespace_class [XmlNamespace, nil] The element's namespace
+        # @return [Boolean] true if declaration needed
+        def needs_declaration?(type_namespace_class, element_namespace_class)
+          return true unless element_namespace_class
+
+          # If element and type have same namespace, element handles it
+          type_namespace_class != element_namespace_class
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    module TypeNamespace
+      autoload :Collector, "#{__dir__}/type_namespace/collector"
+      autoload :Reference, "#{__dir__}/type_namespace/reference"
+      autoload :Resolver, "#{__dir__}/type_namespace/resolver"
+      autoload :Planner, "#{__dir__}/type_namespace/planner"
+      autoload :Declaration, "#{__dir__}/type_namespace/declaration"
+    end
+  end
+end

data/lib/lutaml/xml/type_namespace_resolver.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Xml
+    # Resolves type namespace references from attributes
+    #
+    # LAZY RESOLUTION (Session 126):
+    # Type namespaces are resolved during declaration planning, not collection.
+    # This prevents infinite recursion: collection → type_namespace_class → imports → new collection
+    # Safe to call type_namespace_class during planning - all mappings already imported.
+    #
+    # @example
+    #   resolver = TypeNamespaceResolver.new
+    #   resolver.resolve(needs)
+    #
+    class TypeNamespaceResolver
+      # Initialize resolver with register for type resolution
+      #
+      # @param register [Symbol] the register ID for type resolution
+      def initialize(register = nil)
+        @register = register || Lutaml::Model::Config.default_register
+      end
+
+      # Resolve type namespace references collected during NamespaceCollector phase
+      #
+      # Populates needs.type_namespaces, needs.type_namespace_classes,
+      # needs.type_attribute_namespaces, needs.type_element_namespaces
+      # from needs.type_refs
+      #
+      # @param needs [NamespaceNeeds] Namespace needs structure with type_refs
+      # @return [void]
+      def resolve(needs)
+        type_refs = needs.type_refs
+        return unless type_refs&.any?
+
+        type_refs.each do |ref|
+          attr_rule = ref.rule
+          context = ref.context
+
+          # Resolve type using Reference's mapper_class-aware register resolution
+          type_ns_class = ref.namespace_class(@register)
+          next unless type_ns_class
+
+          # Populate needs just like collector would have
+          needs.add_type_namespace(attr_rule.to, type_ns_class)
+
+          if context == :attribute
+            needs.add_type_attribute_namespace(type_ns_class)
+            usage = :attributes
+          else
+            needs.add_type_element_namespace(type_ns_class)
+            usage = :elements
+          end
+
+          # Track in namespaces hash
+          key = type_ns_class.to_key
+          usage_obj = needs.namespace(key) || NamespaceUsage.new(type_ns_class)
+          usage_obj.used_in << usage
+          needs.add_namespace(key, usage_obj)
+        end
+
+        # Clear type_refs after resolution (no longer needed)
+        needs.clear_type_refs
+
+        # Recursively resolve children
+        needs.children&.each_value do |child_needs|
+          resolve(child_needs)
+        end
+      end
+
+      private
+
+      attr_reader :register
+    end
+  end
+end