lutaml-model 0.8.0 → 0.8.2

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -41,7 +41,7 @@ module Lutaml
         # @return [Object] The deserialized model instance
         def from(format, data, options = {})
           Instrumentation.instrument(:from, model: name, format: format) do
-            adapter = Lutaml::Model::Config.adapter_for(format)
+            adapter = resolve_adapter(format, options.delete(:adapter))
 
             raise Lutaml::Model::FormatAdapterNotSpecifiedError.new(format) if adapter.nil?
 
@@ -130,7 +130,7 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The model instance
         def of(format, doc, options = {})
-          if doc.is_a?(Array) && format != :jsonl
+          if doc.is_a?(Array) && !array_passthrough_format?(format)
             return doc.map { |item| send(:"of_#{format}", item) }
           end
 
@@ -156,6 +156,23 @@ module Lutaml
           # No-op by default; XML overrides via prepend
         end
 
+        # Whether this format+model combination requires the parsed array
+        # to pass through to the transformer as a whole (not split per element).
+        # YAMLS with sequence definitions needs the full document array.
+        #
+        # @param format [Symbol] The format
+        # @return [Boolean]
+        def array_passthrough_format?(format)
+          return true if format == :jsonl
+
+          if format == :yamls
+            mapping = mappings[format]
+            return true if mapping.respond_to?(:yamls_sequence) && mapping.yamls_sequence
+          end
+
+          false
+        end
+
         # Serialize a model instance to a format
         #
         # @param format [Symbol] The format to serialize to
@@ -171,8 +188,13 @@ module Lutaml
         # @return [String] The serialized output
         def to(format, instance, options = {})
           Instrumentation.instrument(:to, model: name, format: format) do
+            adapter_override = options.is_a?(Hash) && options.delete(:adapter)
+            if adapter_override && options.is_a?(Hash)
+              options[:_adapter_override] =
+                true
+            end
             value = public_send(:"as_#{format}", instance, options)
-            adapter = Lutaml::Model::Config.adapter_for(format)
+            adapter = resolve_adapter(format, adapter_override)
 
             # Hook for format-specific options preparation (e.g., XML prefix/namespace/declaration)
             options = prepare_to_options(format, instance, options)
@@ -292,6 +314,23 @@ module Lutaml
             # If a root element is needed, declare it explicitly in xml block
           end
         end
+
+        private
+
+        # Resolve adapter class for a format operation.
+        #
+        # @param format [Symbol] the format name
+        # @param adapter_override [Symbol, Class, nil] per-operation adapter override
+        # @return [Class, nil] the adapter class
+        def resolve_adapter(format, adapter_override)
+          if adapter_override.is_a?(Class)
+            adapter_override
+          elsif adapter_override
+            AdapterResolver.resolved_adapter_class(format, adapter_override)
+          else
+            AdapterResolver.adapter_for(format)
+          end
+        end
       end
     end
   end

data/lib/lutaml/model/serialize.rb

@@ -159,16 +159,18 @@ module Lutaml
         @using_default[attribute_name]
       end
 
-      def method_missing(method_name, *)
+      # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+, but required_ruby_version >= 3.0
+      def method_missing(method_name, *args)
         if method_name.to_s.end_with?("=") && attribute_exist?(method_name)
           define_singleton_method(method_name) do |value|
             instance_variable_set(:"@#{method_name.to_s.chomp('=')}", value)
           end
-          send(method_name, *)
+          send(method_name, *args)
         else
           super
         end
       end
+      # rubocop:enable Style/ArgumentsForwarding
 
       def respond_to_missing?(method_name, include_private = false)
         (method_name.to_s.end_with?("=") && attribute_exist?(method_name)) ||

data/lib/lutaml/model/services/base.rb

@@ -2,8 +2,10 @@ module Lutaml
   module Model
     module Services
       class Base
-        def self.call(*)
-          new(*).call
+        # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
+        def self.call(*args)
+          new(*args).call
+          # rubocop:enable Style/ArgumentsForwarding
         end
       end
     end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.0"
+    VERSION = "0.8.2"
   end
 end

data/lib/lutaml/model.rb

@@ -28,6 +28,8 @@ module Lutaml
     autoload :ContextRegistry, "#{__dir__}/model/context_registry"
     autoload :ImportRegistry, "#{__dir__}/model/import_registry"
     autoload :GlobalContext, "#{__dir__}/model/global_context"
+    autoload :AdapterResolver, "#{__dir__}/model/adapter_resolver"
+    autoload :AdapterScope, "#{__dir__}/model/adapter_scope"
     autoload :Utils, "#{__dir__}/model/utils"
     autoload :Serializable, "#{__dir__}/model/serializable"
     autoload :Error, "#{__dir__}/model/error"

data/lib/lutaml/toml.rb

@@ -30,12 +30,19 @@ Lutaml::Model::FormatRegistry.register(
   adapter_class: nil,
   transformer: Lutaml::Toml::Adapter::Transform,
   key_value: true,
+  adapter_options: if Lutaml::Model::RuntimeCompatibility.opal?
+                     nil
+                   else
+                     {
+                       available: %i[tomlib toml_rb],
+                       default: Lutaml::Model::RuntimeCompatibility.windows? ? :toml_rb : :tomlib,
+                     }
+                   end,
 )
 
 # Register TOML type serializers
 require_relative "toml/type/serializers"
 Lutaml::Toml::Type::Serializers.register_all!
 
-if (adapter = Lutaml::Model::Toml.detect_toml_adapter)
-  Lutaml::Model::Config.toml_adapter_type = adapter
-end
+# Auto-detection is now handled lazily by AdapterResolver on first use.
+# No eager adapter selection at require time.

data/lib/lutaml/xml/serialization/instance_methods.rb

@@ -203,6 +203,12 @@ module Lutaml
         def prepare_instance_format_options(format, options)
           return super unless format == :xml
 
+          # Force eager plan building when adapter is being overridden,
+          # to dereference adapter-specific native nodes before the switch.
+          if @pending_plan_root_element && options[:_adapter_override]
+            import_declaration_plan
+          end
+
           # Handle prefix option (converts to use_prefix for transformation phase)
           if options.key?(:prefix)
             prefix_option = options[:prefix]

data/lib/lutaml/xml.rb

@@ -279,10 +279,9 @@ Lutaml::Model::GlobalContext.register_format_registry(
 # Eagerly load W3C namespace definitions (has registration side effects)
 require_relative "xml/w3c"
 
-# Auto-detect and set default XML adapter
-if (adapter = Lutaml::Xml.detect_xml_adapter)
-  Lutaml::Model::Config.xml_adapter_type = adapter
-end
+# Auto-detection is now handled lazily by AdapterResolver on first use.
+# No eager adapter selection at require time — libraries can configure
+# their preferred adapter before any XML operations occur.
 
 # Namespace identifier validation:
 # - URIs (http://..., urn:...) are valid namespace names per W3C XML

data/lib/lutaml/yaml.rb

@@ -19,6 +19,10 @@ Lutaml::Model::FormatRegistry.register(
   adapter_class: Lutaml::Yaml::Adapter::StandardAdapter,
   transformer: Lutaml::Yaml::Adapter::Transform,
   key_value: true,
+  adapter_options: {
+    available: %i[standard standard_yaml],
+    default: :standard,
+  },
 )
 
 # Register YAML type serializers

data/lib/lutaml/yamls/adapter/mapping.rb

@@ -4,10 +4,17 @@ module Lutaml
   module Yamls
     module Adapter
       class Mapping < Lutaml::KeyValue::Mapping
+        attr_reader :yamls_sequence
+
         def initialize
           super(:yaml)
         end
 
+        def sequence(&)
+          @yamls_sequence = YamlsSequence.new
+          @yamls_sequence.instance_eval(&)
+        end
+
         def deep_dup
           self.class.new.tap do |new_mapping|
             new_mapping.mappings = duplicate_mappings

data/lib/lutaml/yamls/adapter/standard_adapter.rb

@@ -9,13 +9,33 @@ module Lutaml
         FORMAT_SYMBOL = :yamls
 
         def self.parse(yamls, _options = {})
+          parse_with_stream(yamls)
+        end
+
+        def self.parse_with_stream(yamls)
+          results = []
+
+          YAML.load_stream(yamls) do |doc|
+            next if doc.nil?
+
+            results << doc
+          end
+
+          results
+        rescue Psych::SyntaxError => e
+          warn "Skipping invalid yaml: #{e.message}"
+          parse_with_split(yamls)
+        end
+
+        def self.parse_with_split(yamls)
           results = []
 
-          yamls.split(/^---\n/).each do |yaml|
+          yamls.split(/^---\s*$/).each do |yaml|
             next if yaml.strip.empty?
 
             begin
-              results << YAML.safe_load(yaml, aliases: true)
+              doc = YAML.safe_load(yaml, aliases: true)
+              results << doc unless doc.nil?
             rescue Psych::SyntaxError => e
               warn "Skipping invalid yaml: #{e.message}"
             end
@@ -23,6 +43,7 @@ module Lutaml
 
           results
         end
+        private_class_method :parse_with_stream, :parse_with_split
 
         def to_yamls(*_args)
           (@yamls || []).map do |yaml|

data/lib/lutaml/yamls/adapter/transform.rb

@@ -8,17 +8,115 @@ module Lutaml
           mappings = defined_mappings_for(:yamls) || mappings_for(:yaml,
                                                                   lutaml_register)
 
-          super(data, format, options.merge(mappings: mappings))
+          if mappings.is_a?(Mapping) && mappings.yamls_sequence
+            data_to_model_with_sequence(data, format, mappings.yamls_sequence,
+                                        options)
+          else
+            super(data, format, options.merge(mappings: mappings))
+          end
         end
 
         def model_to_data(instance, _format, options = {})
-          # For YAMLS collections, use yamls mappings for this collection
-          # But let nested instances use their own yaml mappings
-          # by passing :yaml format without forcing mappings parameter
-          defined_mappings_for(:yamls) || mappings_for(:yaml, lutaml_register)
+          mappings = defined_mappings_for(:yamls) || mappings_for(:yaml,
+                                                                  lutaml_register)
+
+          if mappings.is_a?(Mapping) && mappings.yamls_sequence
+            model_to_data_with_sequence(instance, mappings.yamls_sequence)
+          else
+            defined = defined_mappings_for(:yamls) || mappings_for(:yaml,
+                                                                   lutaml_register)
+            super(instance, :yaml, options.merge(mappings: defined))
+          end
+        end
+
+        private
+
+        def data_to_model_with_sequence(data_array, format, sequence, options)
+          register = lutaml_register
+          child_register = Lutaml::Model::Register.resolve_for_child(
+            model_class, register
+          )
+
+          instance = if model_class.include?(Lutaml::Model::Serialize)
+                       model_class.new(lutaml_register: child_register)
+                     else
+                       model_class.new
+                     end
+          root_and_parent_assignment(instance, options)
+
+          sequence.rules.each do |rule|
+            docs = extract_docs_for_rule(data_array, rule)
+            next if docs.nil?
+            next if docs.is_a?(Array) && docs.empty?
+
+            if rule.singular?
+              doc = docs.is_a?(Array) ? docs.first : docs
+              value = deserialize_single_doc(doc, rule.type, format,
+                                             register, instance)
+              rule.assign_value(instance, value)
+            else
+              values = docs.map do |doc|
+                deserialize_single_doc(doc, rule.type, format, register,
+                                       instance)
+              end
+              rule.assign_value(instance, values)
+            end
+          end
+
+          instance
+        end
+
+        def extract_docs_for_rule(data_array, rule)
+          size = data_array.size
+          return nil if size.zero?
+
+          case rule.position
+          when Integer
+            idx = rule.position.negative? ? rule.position + size : rule.position
+            data_array[idx]
+          when Range
+            start_idx = rule.position.begin.negative? ? rule.position.begin + size : rule.position.begin
+            end_idx = rule.position.end
+            end_idx = size - 1 if end_idx.nil?
+            end_idx = end_idx + size if end_idx.negative?
+            end_idx = size - 1 if end_idx > size - 1
+            start_idx = 0 if start_idx.negative?
+            return nil if start_idx > end_idx
+
+            data_array[start_idx..end_idx]
+          end
+        end
+
+        def deserialize_single_doc(doc, type, _format, register, parent)
+          transformer = Lutaml::Model::Config.transformer_for(:yaml)
+          transformer.data_to_model(
+            type, doc, :yaml,
+            register: register,
+            lutaml_parent: parent,
+            lutaml_root: parent.lutaml_root || parent
+          )
+        end
+
+        def model_to_data_with_sequence(instance, sequence)
+          results = []
+
+          sequence.rules.each do |rule|
+            value = rule.read_value(instance)
+            next if value.nil?
+
+            if rule.singular?
+              results << serialize_single_model(value)
+            else
+              value.each { |item| results << serialize_single_model(item) }
+            end
+          end
+
+          results
+        end
 
-          # Override format to :yaml - nested instances will auto-select yaml mappings
-          super(instance, :yaml, options)
+        def serialize_single_model(item)
+          transformer = Lutaml::Model::Config.transformer_for(:yaml)
+          transformer.model_to_data(item.class, item, :yaml)
         end
       end
     end

data/lib/lutaml/yamls/adapter/yamls_sequence.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Yamls
+    module Adapter
+      class YamlsSequence
+        attr_reader :rules
+
+        def initialize
+          @rules = []
+        end
+
+        def map_document(position, to:, type:, collection: false)
+          @rules << YamlsSequenceRule.new(position, to: to, type: type,
+                                                    collection: collection)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/yamls/adapter/yamls_sequence_rule.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Yamls
+    module Adapter
+      class YamlsSequenceRule
+        attr_reader :position, :to, :type, :collection
+
+        def initialize(position, to:, type:, collection: false)
+          @position = position
+          @to = to
+          @type = type
+          @collection = collection
+        end
+
+        def resolve_range(doc_count)
+          return nil unless doc_count.positive?
+
+          case position
+          when Integer
+            idx = position.negative? ? position + doc_count : position
+            idx..idx
+          when Range
+            start_idx = position.begin.negative? ? position.begin + doc_count : position.begin
+            end_idx = position.end
+            end_idx = doc_count - 1 if end_idx.nil?
+            end_idx = end_idx + doc_count if end_idx.negative?
+            end_idx = doc_count - 1 if end_idx > doc_count - 1
+            start_idx = 0 if start_idx.negative?
+            start_idx..end_idx
+          end
+        end
+
+        def singular?
+          !collection
+        end
+
+        def assign_value(instance, value)
+          instance.public_send(:"#{to}=", value)
+        end
+
+        def read_value(instance)
+          instance.public_send(to)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/yamls/adapter.rb

@@ -7,6 +7,8 @@ module Lutaml
       autoload :Mapping, "#{__dir__}/adapter/mapping"
       autoload :MappingRule, "#{__dir__}/adapter/mapping_rule"
       autoload :Transform, "#{__dir__}/adapter/transform"
+      autoload :YamlsSequence, "#{__dir__}/adapter/yamls_sequence"
+      autoload :YamlsSequenceRule, "#{__dir__}/adapter/yamls_sequence_rule"
       autoload :StandardAdapter, "#{__dir__}/adapter/standard_adapter"
     end
   end

data/spec/fixtures/geolexica_v2_concept.rb

@@ -0,0 +1,136 @@
+require_relative "../../lib/lutaml/model"
+
+module GeolexicaV2
+  # --- Leaf types ---
+
+  class ContentBlock < Lutaml::Model::Serializable
+    attribute :content, :string
+
+    yaml do
+      map "content", to: :content
+    end
+  end
+
+  class TermDesignation < Lutaml::Model::Serializable
+    attribute :type, :string
+    attribute :normative_status, :string
+    attribute :designation, :string
+
+    yaml do
+      map "type", to: :type
+      map "normative_status", to: :normative_status
+      map "designation", to: :designation
+    end
+  end
+
+  class Locality < Lutaml::Model::Serializable
+    attribute :type, :string
+    attribute :reference_from, :string
+
+    yaml do
+      map "type", to: :type
+      map "reference_from", to: :reference_from
+    end
+  end
+
+  class SourceOrigin < Lutaml::Model::Serializable
+    attribute :ref, :string
+    attribute :locality, Locality
+    attribute :link, :string
+
+    yaml do
+      map "ref", to: :ref
+      map "locality", to: :locality
+      map "link", to: :link
+    end
+  end
+
+  class Source < Lutaml::Model::Serializable
+    attribute :origin, SourceOrigin
+    attribute :type, :string
+
+    yaml do
+      map "origin", to: :origin
+      map "type", to: :type
+    end
+  end
+
+  # --- Document 0: Concept Index ---
+
+  class ConceptIndexData < Lutaml::Model::Serializable
+    attribute :identifier, :string
+    attribute :localized_concepts, :hash
+
+    yaml do
+      map "identifier", to: :identifier
+      map "localized_concepts", to: :localized_concepts
+    end
+  end
+
+  class ConceptIndex < Lutaml::Model::Serializable
+    attribute :data, ConceptIndexData
+    attribute :id, :string
+
+    yaml do
+      map "data", to: :data
+      map "id", to: :id
+    end
+  end
+
+  # --- Document 1: Localized Concept ---
+
+  class LocalizedConceptData < Lutaml::Model::Serializable
+    attribute :definition, ContentBlock, collection: true
+    attribute :examples, ContentBlock, collection: true
+    attribute :notes, ContentBlock, collection: true
+    attribute :sources, Source, collection: true
+    attribute :terms, TermDesignation, collection: true
+    attribute :language_code, :string
+    attribute :entry_status, :string
+
+    yaml do
+      map "definition", to: :definition, render_empty: true
+      map "examples", to: :examples, render_empty: true
+      map "notes", to: :notes, render_empty: true
+      map "sources", to: :sources, render_empty: true
+      map "terms", to: :terms
+      map "language_code", to: :language_code
+      map "entry_status", to: :entry_status
+    end
+  end
+
+  class LocalizedConcept < Lutaml::Model::Serializable
+    attribute :data, LocalizedConceptData
+    attribute :id, :string
+
+    yaml do
+      map "data", to: :data
+      map "id", to: :id
+    end
+  end
+
+  # --- Managed Concept: YAMLS sequence of ConceptIndex + LocalizedConcept ---
+
+  class ManagedConcept < Lutaml::Model::Serializable
+    attribute :index, ConceptIndex
+    attribute :localized, LocalizedConcept, collection: true
+
+    yamls do
+      sequence do
+        map_document 0, to: :index, type: ConceptIndex
+        map_document 1.., to: :localized, type: LocalizedConcept,
+                          collection: true
+      end
+    end
+  end
+
+  # --- Collection of ManagedConcepts (directory of v2 files) ---
+
+  class ManagedConceptCollection < Lutaml::Model::Collection
+    instances :concepts, ManagedConcept
+
+    yamls do
+      map_instances to: :concepts
+    end
+  end
+end

data/spec/fixtures/geolexica_v2_sample.yaml

@@ -0,0 +1,36 @@
+---
+data:
+  identifier: 3.5.8.8
+  localized_concepts:
+    eng: fbe1444a-7c11-555e-bb1b-680a4e6f2502
+id: 0171b198-d068-53d9-8741-fb87e6755d62
+
+---
+data:
+  definition:
+  - content: characteristic of a {{urn:iso:std:iso:14812:3.5.8.1,financial model}}
+      that requires {{urn:iso:std:iso:14812:3.5.3.4,user,users}} to enter into an
+      agreement prior to receiving {{urn:iso:std:iso:14812:3.5.2.1,service,services}}
+  examples: []
+  notes:
+  - content: The agreement can be associated with fees.
+  - content: The agreement can be minimal, such as collecting user information for
+      business purposes.
+  - content: The membership can be granted as a part of a broader agreement. For example,
+      a university bus {{urn:iso:std:iso:14812:3.1.2.1,system}} can restrict access
+      to students and faculty.
+  sources:
+  - origin:
+      ref: ISO/TS 14812:2022
+      locality:
+        type: clause
+        reference_from: 3.5.8.8
+      link: https://www.iso.org/standard/79779.html
+    type: authoritative
+  terms:
+  - type: expression
+    normative_status: preferred
+    designation: membership-based
+  language_code: eng
+  entry_status: valid
+id: fbe1444a-7c11-555e-bb1b-680a4e6f2502

data/spec/fixtures/geolexica_v2_sample2.yaml

@@ -0,0 +1,38 @@
+---
+data:
+  identifier: 3.7.1.5
+  localized_concepts:
+    eng: 0e4dd58e-d197-57af-a4fb-55653e46540d
+id: 01da7814-e090-5c79-8e88-04a40532da50
+
+---
+data:
+  definition:
+  - content: "{{urn:iso:std:iso:14812:3.7.1.4,vehicle input device,input device}}
+      designed to be physically {{urn:iso:std:iso:14812:3.2.3.6,connected}} to a {{urn:iso:std:iso:14812:3.7.1.1,vehicle}}
+      and to remain connected even when the vehicle is not in use"
+  examples: []
+  notes:
+  - content: Built-in input devices include devices that can be temporarily {{urn:iso:std:iso:14812:3.7.4.3,disconnected}}
+      for security reasons (e.g. some radios are equipped with detachable front panels).
+  - content: Built-in input devices are typically considered to be a part of the vehicle.
+  - content: Built-in input devices require a maintenance operation to connect or
+      disconnect.
+  sources:
+  - origin:
+      ref: ISO/TS 14812:2022
+      locality:
+        type: clause
+        reference_from: 3.7.1.5
+      link: https://www.iso.org/standard/79779.html
+    type: authoritative
+  terms:
+  - type: expression
+    normative_status: preferred
+    designation: built-in vehicle input device
+  - type: expression
+    normative_status: preferred
+    designation: built-in input device
+  language_code: eng
+  entry_status: valid
+id: 0e4dd58e-d197-57af-a4fb-55653e46540d