lutaml-lml 0.2.0 → 0.3.0

data/lib/lutaml/lml/model_compiler/validation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Lml
+    class ModelCompiler
+      # Evaluates hydrated instances against their compiled
+      # models (unknown attributes, enum membership, nesting).
+      module Validation
+        private
+
+        def validate_instance(instance, errors, path = 'root')
+          if instance.instance && Array(instance.attributes).empty?
+            validate_instance(instance.instance, errors, "#{path}.instance")
+            return
+          end
+
+          attrs = Array(instance.attributes)
+          type_attr = attrs.find { |a| a.name == 'type' }
+          type_name = type_attr ? type_attr.value.to_s : instance.type
+          klass = @compiled[demodulize(type_name)]
+          unless klass
+            errors << "#{path}: unknown type '#{type_name}'"
+            return
+          end
+
+          schema_attrs = klass.attributes.keys.map(&:to_s)
+          present_attrs = attrs.map(&:name)
+          schema_set = schema_attrs.to_set
+          present_set = present_attrs.to_set
+
+          unknown = present_set - schema_set - Set.new(%w[type])
+          unknown.each do |name|
+            errors << "#{path}.#{name}: attribute not defined on #{type_name}"
+          end
+
+          required = klass.attributes.values
+                          .reject { |v| v.collection? || v.options.key?(:default) }
+                          .to_set { |v| v.name.to_s }
+
+          missing = required - present_set
+          missing.each do |name|
+            errors << "#{path}.#{name}: required attribute missing (cardinality min >= 1)"
+          end
+
+          attrs.each do |attr|
+            next unless schema_attrs.include?(attr.name)
+
+            attr_def = klass.attributes[attr.name.to_sym]
+            next unless attr_def
+
+            next unless attr_def.collection? && attr.instances.any?
+
+            attr.instances.each_with_index do |nested, i|
+              validate_instance(nested, errors, "#{path}.#{attr.name}[#{i}]")
+            end
+          end
+
+          return unless instance.instance
+
+          validate_instance(instance.instance, errors, "#{path}.instance")
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/lml/model_compiler.rb

@@ -4,9 +4,24 @@ require 'json'
 
 module Lutaml
   module Lml
+    # Compiles LML model definitions into anonymous
+    # Lutaml::Model::Serializable subclasses, hydrates instance data
+    # against them, and applies declared serialization mappings. The
+    # concern modules (Hydration, Validation, Enums,
+    # SerializationMappings, StringFormats) share this class's state.
     class ModelCompiler
+      autoload :Hydration, "lutaml/lml/model_compiler/hydration"
+      autoload :Validation, "lutaml/lml/model_compiler/validation"
+      autoload :Enums, "lutaml/lml/model_compiler/enums"
+      autoload :SerializationMappings, "lutaml/lml/model_compiler/serialization_mappings"
+      autoload :StringFormats, "lutaml/lml/model_compiler/string_formats"
+
       class ValidationError < Error; end
 
+      # The default generated namespace nests under Lutaml::Lml so
+      # compiled constants never collide with top-level constants.
+      DEFAULT_NAMESPACE = 'Lutaml::Lml::Generated'
+
       TYPE_MAP = {
         'String' => :string,
         'string' => :string,
@@ -20,13 +35,19 @@ module Lutaml
         'date_time' => :date_time,
         'DateTime' => :date_time,
         'Time' => :time,
-        'Uri' => :string
+        'Uri' => :string,
       }.freeze
 
       # Tokens that denote unbounded cardinality in LML attribute
       # declarations. Anything else must parse as an Integer.
       UNBOUNDED_TOKENS = %w[* n N unbounded].freeze
 
+      include Hydration
+      include Validation
+      include Enums
+      include SerializationMappings
+      include StringFormats
+
       def initialize(namespace: nil, artifact_paths: {}, default_artifact: nil)
         @namespace = namespace
         @artifact_paths = artifact_paths
@@ -81,117 +102,6 @@ module Lutaml
 
       private
 
-      def validate_instance(instance, errors, path = 'root')
-        if instance.instance && Array(instance.attributes).empty?
-          validate_instance(instance.instance, errors, "#{path}.instance")
-          return
-        end
-
-        attrs = Array(instance.attributes)
-        type_attr = attrs.find { |a| a.name == 'type' }
-        type_name = type_attr ? type_attr.value.to_s : instance.type
-        klass = @compiled[demodulize(type_name)]
-        unless klass
-          errors << "#{path}: unknown type '#{type_name}'"
-          return
-        end
-
-        schema_attrs = klass.attributes.keys.map(&:to_s)
-        present_attrs = attrs.map(&:name)
-        schema_set = schema_attrs.to_set
-        present_set = present_attrs.to_set
-
-        unknown = present_set - schema_set - Set.new(%w[type])
-        unknown.each do |name|
-          errors << "#{path}.#{name}: attribute not defined on #{type_name}"
-        end
-
-        required = klass.attributes.select do |_k, v|
-          !v.collection? && !v.options.key?(:default)
-        end.keys.map(&:to_s).to_set
-
-        missing = required - present_set
-        missing.each do |name|
-          errors << "#{path}.#{name}: required attribute missing (cardinality min >= 1)"
-        end
-
-        attrs.each do |attr|
-          next unless schema_attrs.include?(attr.name)
-
-          attr_def = klass.attributes[attr.name.to_sym]
-          next unless attr_def
-
-          next unless attr_def.collection? && attr.instances.any?
-
-          attr.instances.each_with_index do |nested, i|
-            validate_instance(nested, errors, "#{path}.#{attr.name}[#{i}]")
-          end
-        end
-
-        return unless instance.instance
-
-        validate_instance(instance.instance, errors, "#{path}.instance")
-      end
-
-      def hydrate_instance(instance)
-        inner = instance.instance
-        return hydrate_instance(inner) if inner && Array(instance.attributes).empty?
-
-        type_name = resolve_instance_type(instance)
-        klass = @compiled[type_name]
-        return hydrate_as_untyped(instance, type_name) unless klass
-
-        attrs = extract_instance_attributes(instance, klass)
-        klass.new(**attrs)
-      end
-
-      def resolve_instance_type(instance)
-        # L6: the explicit isa keyword is the type override; a `type`
-        # attribute is ordinary data (pubid's identifier-kind field)
-        return demodulize(instance.isa.to_s) if instance.isa
-
-        demodulize(instance.type.to_s)
-      end
-
-      def demodulize(name)
-        name.split('::').last.to_s
-      end
-
-      def hydrate_as_untyped(instance, type_name)
-        { _name: type_name, **extract_raw_attributes(instance) }
-      end
-
-      def extract_raw_attributes(instance)
-        instance.each_attribute.each_with_object({}) do |(name, value, nested), hash|
-          hash[name.to_sym] = resolve_instance_value(value, nested)
-        end
-      end
-
-      def extract_instance_attributes(instance, klass)
-        schema_keys = klass.attributes.keys.to_set
-        instance.each_attribute.each_with_object({}) do |(name, value, nested), hash|
-          key = name.to_sym
-          next unless schema_keys.include?(key)
-
-          hash[key] = resolve_instance_value(value, nested, klass.attributes[key])
-        end
-      end
-
-      def resolve_instance_value(value, nested, attr_def = nil)
-        if nested.any?
-          nested.map { |i| hydrate_instance(i) }
-        elsif value.is_a?(Array)
-          value
-        elsif (enum_class = attr_def && enum_class_for(attr_def.type))
-          value_name = enum_value_name(value.to_s)
-          description = enum_class.values
-                                  .find { |v| v.name == value_name }&.description
-          enum_class.new(value: value_name, description: description)
-        elsif !value.nil?
-          value
-        end
-      end
-
       def compile_document(doc)
         @declared_namespaces = Array(doc.namespaces)
         @serialization_mappings = Array(doc.serialization_mappings)
@@ -205,18 +115,6 @@ module Lutaml
         register_string_formats(doc)
       end
 
-      # In-class `mapping <format> { … }` is the shortcut for a sibling
-      # mapping targeting the enclosing class; hoist them so emission is
-      # uniform.
-      def hoist_class_serialization_mappings(doc)
-        (Array(doc.classes) + Array(doc.data_types)).each do |klass_def|
-          Array(klass_def.serialization_mappings).each do |mapping|
-            mapping.target = klass_def.name.to_s
-            @serialization_mappings << mapping
-          end
-        end
-      end
-
       def resolve_forward_references
         @forward_refs.each do |class_name, deferred_attrs|
           klass = @compiled[class_name]
@@ -237,57 +135,7 @@ module Lutaml
         register(name, compiled_klass)
       end
 
-      # Emit the lutaml-model mapping blocks declared in the LML source:
-      #   mapping yaml { map "full-name", to: "name" }
-      # becomes klass.yml do |m| m.map "full-name", to: :name end
-      def apply_declared_mappings(compiled_klass, def_obj)
-        return unless def_obj.is_a?(UmlClass) || def_obj.is_a?(DataType)
-
-        def_obj.wire_mappings.to_a.group_by(&:format).each do |format, entries|
-          next unless format && Lutaml::Model::FormatRegistry.registered?(format.to_sym)
-
-          compiled_klass.public_send(format) do |mapping|
-            entries.each { |entry| mapping.map(entry.wire, to: entry.to.to_sym) }
-          end
-        end
-      end
-
       alias compile_data_type compile_class
-
-      EnumValue = Struct.new(:name, :description, :payload)
-
-      def compile_enum(enum_def)
-        name = enum_def.name.to_s
-        expand_from_table(enum_def)
-        values = extract_enum_values(enum_def)
-
-        payload_fields = Array(enum_def.member_fields).map(&:name).map(&:to_s)
-        compiled_klass = Class.new(Lutaml::Model::Serializable) do
-          attribute :value, :string, default: values.first.name
-          attribute :description, :string
-          payload_fields.each do |field|
-            attribute field.to_sym, :string
-          end
-
-          define_method(:to_s) { value }
-        end
-
-        values.each do |value|
-          accessor = value.name.to_s.gsub(/[^a-zA-Z0-9_]/, '_')
-          compiled_klass.define_singleton_method(accessor) do
-            new({ value: value.name, description: value.description }.merge(value.payload || {}))
-          end
-        end
-        compiled_klass.define_singleton_method(:values) { values }
-
-        @enum_names << name
-        @enum_classes[name] = compiled_klass
-        register(name, compiled_klass)
-      end
-
-      # Builds a compiled Serializable subclass from a class or data-type
-      # definition: declares attributes and stashes forward-referenced
-      # attributes for post-registration resolution.
       def build_compiled_class(def_obj)
         all_attrs = build_attributes(def_obj)
         immediate, deferred = all_attrs.partition do |(_, raw_type, type, _)|
@@ -318,125 +166,6 @@ module Lutaml
         compiled_klass
       end
 
-      # Apply a lutaml-model XML mapping to each compiled class so they
-      # support from_xml/to_xml. Runs after forward references are resolved
-      # so all attributes (immediate + deferred) get element mappings.
-      def apply_xml_mappings
-        @compiled.each do |name, klass|
-          next if @enum_names.include?(name)
-
-          custom = serialization_mapping_for(name, 'xml')
-          next apply_custom_xml_mapping(klass, custom) if custom
-
-          apply_xml_mapping(klass, name)
-        end
-      end
-
-      def apply_xml_mapping(klass, root_name)
-        attr_names = klass.attributes.keys
-        return if attr_names.empty?
-
-        klass.xml do |mapping|
-          mapping.root(root_name)
-          attr_names.each do |attr_name|
-            mapping.map_element(attr_name.to_s, to: attr_name)
-          end
-        end
-      end
-
-      # RS 3010 extension: key-value mapping blocks for the declared
-      # formats (yaml/json/toml share lutaml-model's key_value model).
-      def apply_key_value_mappings
-        @compiled.each do |name, klass|
-          next if @enum_names.include?(name)
-
-          custom = serialization_mapping_for(name, 'key_value')
-          apply_custom_key_value_mapping(klass, custom) if custom
-        end
-      end
-
-      def serialization_mapping_for(target, format)
-        @serialization_mappings.find do |m|
-          m.target.to_s == target && serialization_format(m.format) == format
-        end
-      end
-
-      def serialization_format(format)
-        %w[yaml json toml].include?(format.to_s) ? 'key_value' : format.to_s
-      end
-
-      def apply_custom_xml_mapping(klass, mapping)
-        check_namespace_ambiguity(mapping)
-        ns_class = namespace_class_for(mapping.namespace_ref) if mapping.namespace_ref
-        rule_ns = mapping.rules.select { |r| r.kind == 'namespace' }
-                               .to_h { |r| [r.field, namespace_class_for(r.field)] }
-        klass.xml do |m|
-          m.root(mapping.element_name) if mapping.element_name
-          m.namespace(ns_class) if ns_class
-          m.mixed_content if mapping.mixed_content
-          mapping.rules.each do |rule|
-            case rule.kind
-            when 'element' then m.map_element(rule.wire, to: rule.field.to_sym)
-            when 'attribute' then m.map_attribute(rule.wire, to: rule.field.to_sym)
-            when 'content' then m.map_content(to: rule.field.to_sym)
-            when 'namespace' then m.namespace(rule_ns[rule.field])
-            end
-          end
-        end
-      end
-
-      def apply_custom_key_value_mapping(klass, mapping)
-        formats = mapping.format.to_s == 'key_value' ? %w[yaml json toml] : [mapping.format.to_s]
-        klass.instance_eval do
-          formats.each do |format|
-            public_send(format) do |m|
-              mapping.rules.each do |rule|
-                case rule.kind
-                when 'map' then m.map(rule.wire, to: rule.field.to_sym)
-                when 'key' then m.map_key(to_instance: rule.field.to_sym)
-                when 'value'
-                  if rule.mode == 'as_attribute'
-                    m.map_value(as_attribute: rule.field.to_sym)
-                  else
-                    m.map_value(to_instance: rule.field.to_sym)
-                  end
-                end
-              end
-            end
-          end
-        end
-      end
-
-      def check_namespace_ambiguity(mapping)
-        return unless mapping.format.to_s == 'xml'
-        return if mapping.namespace_ref || @declared_namespaces.length < 2
-
-        raise ArgumentError,
-              "mapping #{mapping.format} #{mapping.target}: ambiguous default " \
-              "namespace — #{@declared_namespaces.length} namespaces in scope " \
-              "(#{@declared_namespaces.map(&:name).join(', ')}); declare one with " \
-              "'namespace <name>'"
-      end
-
-      def namespace_class_for(ref)
-        return nil if ref.nil?
-
-        require "lutaml/xml/namespace" unless defined?(Lutaml::Xml::Namespace)
-
-        ns_class = @namespace_classes[ref]
-        return ns_class if ns_class
-
-        declared = @declared_namespaces.find { |ns| ns.name.to_s == ref }
-        raise ArgumentError, "unknown namespace '#{ref}'" unless declared
-
-        ns_class = Class.new(Lutaml::Xml::Namespace)
-        uri = declared.uri
-        prefix = declared.prefix.to_s
-        ns_class.define_singleton_method(:uri) { uri }
-        ns_class.define_singleton_method(:prefix_default) { prefix }
-        @namespace_classes[ref] = ns_class
-      end
-
       def build_attributes(klass_def)
         Array(klass_def.attributes).map do |attr|
           attr_name = attr.name.to_sym
@@ -447,33 +176,12 @@ module Lutaml
         end
       end
 
-      # RS 3001 §Attribute: `values { v1, v2 }` expands into an anonymous
-      # enum baked from the inline set; the attribute is typed with it.
-      def resolve_values_type(klass_def, attr)
-        return attr.type.to_s unless attr.value_set&.any?
-
-        enum_name = anonymous_enum_name(klass_def.name, attr.name)
-        members = attr.value_set.map { |v| ::Lutaml::Lml::TopElementAttribute.new(name: v.to_s) }
-        compile_enum(::Lutaml::Lml::Enum.new(name: enum_name, attributes: members))
-        enum_name
-      end
-
-      def anonymous_enum_name(class_name, attr_name)
-        base = class_name.to_s.split('::').last
-        attr_part = attr_name.to_s.split('_').map(&:capitalize).join
-        "#{base}#{attr_part}Values"
-      end
-
       def resolve_type(type_name)
-        if TYPE_MAP.key?(type_name)
-          TYPE_MAP[type_name]
-        elsif type_name.start_with?('reference:(')
-          :string
-        elsif @compiled.key?(type_name)
-          @compiled[type_name]
-        else
-          :string
-        end
+        return TYPE_MAP[type_name] if TYPE_MAP.key?(type_name)
+        return :string if type_name.start_with?('reference:(')
+        return @compiled[type_name] if @compiled.key?(type_name)
+
+        :string
       end
 
       def build_options(attr)
@@ -489,9 +197,9 @@ module Lutaml
         min = parse_cardinality_value(card.min)
         max = parse_cardinality_value(card.max)
 
-        if max && (max > 1 || max == Float::INFINITY)
-          options[:collection] = true
-        elsif max.nil? && min && min > 1
+        collection = (max && (max > 1 || max == Float::INFINITY)) ||
+                     (max.nil? && min && min > 1)
+        if collection
           options[:collection] = true
         elsif min.zero?
           options[:default] = nil
@@ -519,9 +227,8 @@ module Lutaml
       # render_nil is a lutaml-model MAPPING option, not an attribute
       # option: collect the declaration for the mapping passes
       def declared_render_nil(attr)
-        Array(attr.properties).find do |prop|
-          prop.name.to_s == 'render_nil'
-        end&.then { |prop| prop.value.to_s == 'true' }
+        prop = Array(attr.properties).find { |prop| prop.name.to_s == 'render_nil' }
+        prop ? prop.value.to_s == 'true' : nil
       end
 
       def parse_cardinality_value(val)
@@ -532,104 +239,6 @@ module Lutaml
         raise ValidationError, "Unrecognized cardinality token: #{val.inspect}"
       end
 
-      # L7a point 3: from_table members are baked at compile time — the
-      # artifact table's rows become the values, validated against the
-      # declared member_fields (unknown field = error; missing = nil).
-      # The member name comes from the row's "name" column.
-      def expand_from_table(enum_def)
-        return unless enum_def.from_table_name
-
-        rows = artifact_table_rows(enum_def)
-        known = Array(enum_def.member_fields).map { |f| f.name.to_s }
-        rows.each do |row|
-          row = row.transform_keys(&:to_s)
-          member_name = row.fetch('name')
-          unknown = row.keys - known - ['name']
-          if unknown.any?
-            raise ArgumentError,
-                  "enum #{enum_def.name}: table row #{member_name.inspect} has " \
-                  "undeclared fields #{unknown.inspect} (declared: #{known.inspect})"
-          end
-          payload = row.slice(*known).compact
-          enum_def.attributes << TopElementAttribute.new(
-            name: member_name,
-            properties: payload.map do |field, value|
-              TopElementAttribute.new(name: field, value: value)
-            end
-          )
-        end
-      end
-
-      def artifact_table_rows(enum_def)
-        reference = enum_def.from_table_artifact || @default_artifact
-        path = artifact_path_for(reference.to_s)
-        unless path
-          raise ArgumentError,
-                "enum #{enum_def.name}: from_table artifact #{reference.inspect} not found"
-        end
-
-        envelope = JSON.parse(File.read(path))
-        table = envelope['tables'].to_h[enum_def.from_table_name]
-        unless table
-          raise ArgumentError,
-                "enum #{enum_def.name}: table #{enum_def.from_table_name.inspect} " \
-                "not found in artifact #{reference.inspect}"
-        end
-
-        table['rows'].to_a
-      end
-
-      def extract_enum_values(enum_def)
-        member_fields = Array(enum_def.member_fields).map do |f|
-          [f.name.to_s, f.type.to_s]
-        end
-        enum_def.attributes.map do |attr|
-          description = member_description(attr)
-          payload = extract_member_payload(attr)
-          validate_member_payload(enum_def, attr, payload, member_fields)
-          EnumValue.new(attr.name.to_s, description, payload)
-        end
-      end
-
-      # The member description rides a nested attribute named `description`
-      # (bare-member form) or `definition` (RS 3001 `value` blocks); both
-      # spellings are accepted.
-      def member_description(attr)
-        nested = Array(attr.attributes).find do |n|
-          %w[description definition].include?(n.name.to_s)
-        end
-        text = nested&.type || nested&.definition || nested&.value
-        text.is_a?(Hash) && text.key?(:string) ? text[:string] : text
-      end
-
-      # L7a: per-member payload lines ride the keyword-attribute
-      # properties (`abbreviation = "WD"`)
-      def extract_member_payload(attr)
-        Array(attr.properties).to_h { |p| [p.name.to_s, p.value&.to_s] }
-      end
-
-      def validate_member_payload(enum_def, attr, payload, member_fields)
-        known = member_fields.map(&:first)
-        unknown = payload.keys - known
-        return unless unknown.any?
-
-        raise ArgumentError,
-              "enum #{enum_def.name}: member #{attr.name} has undeclared " \
-              "payload fields #{unknown.inspect} (declared: #{known.inspect})"
-      end
-
-      def enum_class_for(type)
-        type.is_a?(Class) && @enum_classes.value?(type) and return type
-      end
-
-      def enum_value_name(raw)
-        raw.split('::').last
-      end
-
-      # L7b: derived fields declare existence + type; computation is
-      # bound by the binder from artifact derive specs. The attribute
-      # participates in mappings like any other (relaton consumes URNs
-      # from model JSON).
       def declare_derived_fields(compiled_klass, def_obj)
         return unless def_obj.is_a?(UmlClass) || def_obj.is_a?(DataType)
 
@@ -647,35 +256,6 @@ module Lutaml
         end
       end
 
-      # L5: register grammar-backed string formats. Class-level
-      # declarations win; a models-block default applies to classes
-      # without their own. Artifact resolution: the compiler's
-      # artifacts map (name => path), else the string as a path.
-      def register_string_formats(doc)
-        defaults = doc.packages.flat_map(&:default_string_formats)
-        doc.classes.each do |class_def|
-          declared = Array(class_def.string_formats)
-          declared.each { |fmt| register_string_format(class_def.name.to_s, fmt) }
-
-          declared_formats = declared.map(&:format)
-          defaults.reject { |fmt| declared_formats.include?(fmt.format) }
-                  .each { |fmt| register_string_format(class_def.name.to_s, fmt) }
-        end
-      end
-
-      def register_string_format(class_name, fmt)
-        artifact_path = artifact_path_for(fmt.artifact.to_s)
-        return unless artifact_path
-
-        compiled = @compiled[class_name]
-        return unless compiled
-
-        Parsanol::PARG::Lutaml.register(compiled,
-                                        format_name: fmt.format.to_sym,
-                                        artifact: artifact_path,
-                                        entry: fmt.root.to_s)
-      end
-
       def artifact_path_for(reference)
         mapped = @artifact_paths && @artifact_paths[reference]
         return mapped if mapped && File.exist?(mapped.to_s)
@@ -700,7 +280,20 @@ module Lutaml
         @compiled[name] = klass
         return unless @namespace
 
-        @namespace.const_set(name, klass)
+        namespace_module.const_set(name, klass)
+      end
+
+      def namespace_module
+        return @namespace if @namespace.is_a?(Module)
+
+        @namespace_module ||= begin
+          chain = @namespace.to_s.split('::')
+          chain.reduce(Object) do |parent, name|
+            parent.const_get(name)
+          rescue NameError
+            parent.const_set(name, Module.new)
+          end
+        end
       end
     end
   end

data/lib/lutaml/lml/models/document.rb

@@ -17,6 +17,9 @@ module Lutaml
       attribute :enums, "Lutaml::Lml::Enum", collection: true, default: -> { [] }
       attribute :packages, "Lutaml::Lml::Package", collection: true, default: -> { [] }
       attribute :namespaces, "Lutaml::Lml::Namespace", collection: true, default: -> { [] }
+      # `models <Name> version "x.y.z"` headers: model name -> declared
+      # version (issue #16, the co-release identity line).
+      attribute :model_versions, :hash, default: -> { {} }
       attribute :serialization_mappings, "Lutaml::Lml::SerializationMapping", collection: true, default: -> { [] }
       attribute :primitives, "Lutaml::Lml::PrimitiveType", collection: true, default: -> { [] }
       attribute :associations, "Lutaml::Lml::Association", collection: true, default: -> { [] }
@@ -27,6 +30,32 @@ module Lutaml
       attribute :instance, "Lutaml::Lml::Instance"
       attribute :requires, :string, collection: true, default: -> { [] }
       attribute :instances, "Lutaml::Lml::InstanceCollection"
+
+      # Repeated `instances` blocks accumulate (issue #17): instances,
+      # imports, exports and collections concat; a duplicate collection
+      # name is an error (same name is a mistake, distinct names intent).
+      def instances=(collection)
+        collection = Lutaml::Lml::InstanceCollection.new(**collection) if collection.is_a?(Hash)
+        if @instances.nil? || (@instances.instances.empty? && @instances.imports.empty? &&
+            @instances.exports.empty? && @instances.collections.empty?)
+          @instances = collection
+        else
+          merge_instances(collection)
+        end
+      end
+
+      def merge_instances(incoming)
+        names = @instances.collections.map(&:name)
+        incoming.collections.each do |collection|
+          if names.include?(collection.name)
+            raise Lutaml::Lml::Error, "duplicate collection name '#{collection.name}'"
+          end
+        end
+        @instances.instances.concat(incoming.instances)
+        @instances.imports.concat(incoming.imports)
+        @instances.exports.concat(incoming.exports)
+        @instances.collections.concat(incoming.collections)
+      end
       attribute :view_imports, "Lutaml::Lml::ViewImport", collection: true, default: -> { [] }
       attribute :show_filter, "Lutaml::Lml::ViewFilter"
       attribute :hide_filter, "Lutaml::Lml::ViewFilter"