lutaml-model 0.8.126 → 0.8.128

data/lib/lutaml/key_value/transform.rb

@@ -97,7 +97,9 @@ module Lutaml
         # NEW ARCHITECTURE: Use KeyValue::Transformation if available
         # This provides symmetric OOP architecture with XmlDataModel
         if context.is_a?(Class) && context.include?(Lutaml::Model::Serialize)
-          transformation = context.transformation_for(format, lutaml_register)
+          transformation = context.transformation_for(
+            format, lutaml_register, mapping: @lutaml_mapping_override
+          )
 
           # transformation_for returns nil for cyclic dependencies or :building sentinel
           # Fall back to legacy approach in these cases
@@ -213,18 +215,26 @@ module Lutaml
 
         mapping = model_class.mappings_for(format, register)
         return false if mapping.nil?
-        # The catch-all collect runs on the interpretive walk only —
-        # the compiled hydration must not skip unknown keys silently.
-        return false if mapping.unmapped_attribute
 
         attrs = model_class.attributes(register)
+        # The catch-all compiles as a row: unclaimed document keys are
+        # collected into the target attribute after the rules hydrate,
+        # mirroring the interpretive collect's position and merge. A
+        # typo'd target raises here, exactly as the walk raises at
+        # first parse.
+        unmapped_target = mapping.unmapped_attribute
+        if unmapped_target && !attrs.key?(unmapped_target)
+          raise ArgumentError,
+                "map_unmapped target :#{unmapped_target} is not a " \
+                "declared attribute of #{model_class}"
+        end
         rows = nil
+        claimed = nil
         mapping.mappings(register).each do |rule|
           eligible = !rule.name.nil? && !rule.multiple_mappings? &&
             rule.delegate.nil? &&
             !rule.has_custom_method_for_deserialization? &&
             !rule.raw_mapping? && !rule.root_mapping? &&
-            !rule.hash_mappings && rule.child_mappings.nil? &&
             rule.when_attribute.empty? &&
             !(if rule.polymorphic.is_a?(::Hash)
                 !rule.polymorphic.empty?
@@ -250,6 +260,24 @@ module Lutaml
           return false if Lutaml::Model::GlobalContext.context(register)
             .substitution_for(type).any?
 
+          if rule.hash_mappings
+            # #1003: compiled child-map row. The compiled ChildMapPlan
+            # reproduces translate_mappings' per-child lookups; shapes
+            # the compile cannot cover (unmappable child attribute,
+            # singular target, non-model child type) keep the whole
+            # model interpretive.
+            return false unless attr.collection? &&
+              type.is_a?(Class) && type.include?(Lutaml::Model::Serialize)
+
+            child_plan = compile_group_child_plan(type, format, register,
+                                                  rule.hash_mappings)
+            return false unless child_plan
+
+            rows ||= []
+            rows << [rule, attr, :child_map, child_plan, nil, nil]
+            next
+          end
+
           if type.is_a?(Class) && type.include?(Lutaml::Model::Serialize)
             child_register = Lutaml::Model::Register
               .resolve_for_child(type, register)
@@ -270,10 +298,45 @@ module Lutaml
             return false
           end
         end
+        if unmapped_target
+          claimed = {}
+          mapping.mappings(register).each do |rule|
+            Array(rule.name).each { |name| claimed[name.to_s] = true } if rule.name
+          end
+          claimed.freeze
+          (rows ||= []) << [nil, nil, :unmapped, unmapped_target, claimed,
+                            nil]
+        end
         # No eligible rows at all (empty mapping) — nothing to gain.
         rows
       end
 
+      # Class-level twin of the walk's child-map compile: the registry
+      # lookups (child rules, per-attribute wire names, path casts)
+      # resolve once per plan instead of once per node per child. nil
+      # keeps the model interpretive (preserving the walk's raise
+      # timing for declaration errors).
+      def self.compile_group_child_plan(child_class, format, register,
+child_mappings)
+        child_rules = child_class.mappings_for(format, register)
+        wire_names = {}
+        paths = {}
+        child_mappings.each do |attr_name, path|
+          attr_rule = child_rules.find_by_to!(attr_name)
+          wire_names[attr_name] = attr_rule.from.to_s
+          paths[attr_name] = case path
+                             when :key then :key
+                             when :value then :value
+                             else Array(path).map(&:to_s).freeze
+                             end
+        end
+        ChildMapPlan.new(child_mappings, wire_names, paths,
+                         child_mappings.values == [:key], child_rules,
+                         child_class)
+      rescue Lutaml::Model::NoMappingFoundError
+        nil
+      end
+
       # Build values bottom-up, then ONE instance per model: present
       # keys through the casting setters, ABSENT rules through the real
       # per-rule walk (their extractor/defaults/sentinel semantics are
@@ -287,7 +350,13 @@ module Lutaml
         # Lazy: the present-key hot path never pushes, and this runs
         # once per hydrated model instance.
         absent = nil
+        unmapped = nil
         rows.each do |rule, attr, kind, type, child_rows, child_register|
+          if kind == :unmapped
+            unmapped = [type, child_rows]
+            next
+          end
+
           # One hash pass per row: fetch with a sentinel distinguishes
           # absent keys from present-nil values (both read as nil), so
           # the separate string_or_symbol_key? probe goes away.
@@ -297,6 +366,33 @@ module Lutaml
             next
           end
 
+          if kind == :child_map
+            # Compiled translate_mappings (#1003): per-child lookups
+            # are plan constants. Children hydrate through their own
+            # compiled walk (the mappings: option routes them there);
+            # parent/root wiring rides the shared children pass. A
+            # non-Hash value falls back to the walk, which owns that
+            # error.
+            return nil unless v.is_a?(::Hash)
+
+            built = []
+            keys_only = type.keys_only && v.values.all?(::Hash)
+            v.each do |child_key, child_value|
+              child_hash = {}
+              type.child_mappings.each_key do |attr_name|
+                child_hash[type.wire_names[attr_name]] =
+                  extract_compiled_child_value(type.paths[attr_name],
+                                               child_key, child_value)
+              end
+              child_hash.update(child_value) if keys_only
+              built << self.class.data_to_model(type.attr_type,
+child_hash, format, { mappings: type.child_rules })
+            end
+            setters << [rule.kv_setter, built]
+            children.concat(built)
+            next
+          end
+
           if kind == :scalar
             setters << [rule.kv_setter, v]
             next
@@ -343,6 +439,20 @@ module Lutaml
           child.lutaml_parent = instance
           child.lutaml_root ||= instance.lutaml_root || instance
         end
+        if unmapped
+          target, claimed = unmapped
+          extras = nil
+          doc.each do |key, value|
+            next if claimed.key?(key.to_s)
+
+            (extras ||= {})[key] = value
+          end
+          if extras
+            existing = instance.public_send(target)
+            merged = existing.is_a?(::Hash) ? existing.merge(extras) : extras
+            instance.public_send(:"#{target}=", merged)
+          end
+        end
         instance
       end
 
@@ -475,12 +585,14 @@ options)
         generate_remaining_mappings_for_value(child_mappings, value, format)
 
         attr_type = attr.type(lutaml_register)
-        value.each do |child_obj|
-          rules = attr_type.mappings_for(format)
+        rules = attr_type.mappings_for(format)
+        pairs = child_mappings.map do |attr_name, path|
+          [rules.find_by_to!(attr_name), path]
+        end
 
+        value.each do |child_obj|
           hash.merge!(
-            extract_hash_for_child_mapping(child_mappings, child_obj, rules,
-                                           format),
+            extract_hash_for_child_mapping(pairs, child_obj, format),
           )
         end
 
@@ -508,14 +620,12 @@ options)
         mappings.find_by_to(name)&.name.to_s
       end
 
-      def extract_hash_for_child_mapping(child_mappings, child_obj, rules,
-format)
+      def extract_hash_for_child_mapping(pairs, child_obj, format)
         key = nil
         value = {}
 
-        child_mappings.each do |attr_name, path|
-          rule = rules.find_by_to!(attr_name)
-          attr_value = normalize_attribute_value(child_obj, rule.from, format)
+        pairs.each do |rule, path|
+          attr_value = normalize_attribute_value(child_obj, rule, format)
 
           next unless rule&.render?(attr_value, nil)
           next key = attr_value if path == :key
@@ -527,10 +637,16 @@ format)
         { key => value }
       end
 
-      def normalize_attribute_value(value, attr_name, format)
-        Lutaml::Model::Config.adapter_for(format).parse(
-          value.public_send(:"to_#{format}"),
-        )[attr_name.to_s]
+      # The child's wire-form value for one attribute, produced through
+      # the same pipeline the child's own serializer uses for a rendered
+      # value (rule transform, then attribute serialization) — without
+      # the serialize-parse string round-trip this read previously paid
+      # per child per attribute.
+      def normalize_attribute_value(child_obj, rule, format)
+        child_attr = child_obj.class.attributes(lutaml_register)[rule.to]
+        value = child_obj.public_send(rule.to)
+        value = rule.transform_value(child_attr, value, :to, format)
+        child_attr.serialize(value, format, lutaml_register)
       end
 
       def extract_hash_value_for_child_mapping(path, value, map_value)
@@ -764,8 +880,14 @@ partition = nil)
         # crashed translate_mappings).
         return if value.nil? && kind == :hash_map
 
-        value = translate_mappings(value, rule.hash_mappings, attr, format,
-                                   instance)
+        child_plan = plan.child_map
+        value = if child_plan
+                  translate_child_map_compiled(value, child_plan, attr,
+                                               format, instance)
+                else
+                  translate_mappings(value, rule.hash_mappings, attr, format,
+                                     instance)
+                end
         unless kind == :hash_map
           value = cast_value(value, attr, format, rule,
                              instance)
@@ -798,12 +920,86 @@ partition = nil)
       # (custom methods, transforms, value maps, delegates, hash mappings,
       # unions, polymorphism) return nil and keep the interpretive path.
       WalkPlan = ::Struct.new(:kind, :attr, :valid, :wire, :klass,
-                              :collection)
+                              :collection, :child_map)
+
+      # Compiled child-map translation (#986b): the per-node registry
+      # lookups (attribute type, child mapping rules, per-attribute wire
+      # names, path string casts) collapse to per-rule constants. nil
+      # child_map keeps the interpretive translate path (including its
+      # declaration-error timing).
+      ChildMapPlan = ::Struct.new(:child_mappings, :wire_names, :paths,
+                                  :keys_only, :child_rules, :attr_type)
 
       # Memoized (per transform) wire name for plain rules — the from
       # spelling never changes after definition.
       KvSerializePlan = ::Struct.new(:wire)
 
+      def build_child_map_plan(format, rule, attr)
+        child_mappings = rule.hash_mappings
+        return nil unless child_mappings.is_a?(::Hash)
+
+        attr_type = attr.type(lutaml_register)
+        return nil unless attr_type.is_a?(Class) &&
+          attr_type.include?(Lutaml::Model::Serialize)
+
+        child_rules = attr_type.mappings_for(format, lutaml_register)
+        wire_names = {}
+        paths = {}
+        child_mappings.each do |attr_name, path|
+          attr_rule = child_rules.find_by_to!(attr_name)
+          wire_names[attr_name] = attr_rule.from.to_s
+          paths[attr_name] = compile_child_map_path(path)
+        end
+        ChildMapPlan.new(child_mappings, wire_names, paths,
+                         child_mappings.values == [:key], child_rules,
+                         attr_type)
+      rescue Lutaml::Model::NoMappingFoundError
+        nil
+      end
+
+      def compile_child_map_path(path)
+        case path
+        when :key then :key
+        when :value then :value
+        else Array(path).map(&:to_s).freeze
+        end
+      end
+
+      # Compiled translate_mappings (#986b). Same shape as the
+      # interpretive pair: keys_only is decided once per rule VALUE (the
+      # original tests the whole document hash, not each child).
+      def translate_child_map_compiled(value, child_plan, attr, format,
+                                       instance)
+        child_options = {
+          mappings: child_plan.child_rules,
+          lutaml_parent: instance,
+          lutaml_root: instance.lutaml_root || instance,
+        }
+        keys_only = child_plan.keys_only && value.values.all?(::Hash)
+        wire_names = child_plan.wire_names
+        paths = child_plan.paths
+        child_mappings = child_plan.child_mappings
+
+        value.map do |key, child_value|
+          child_hash = {}
+          child_mappings.each_key do |attr_name|
+            child_hash[wire_names[attr_name]] =
+              extract_compiled_child_value(paths[attr_name], key, child_value)
+          end
+          child_hash.merge!(child_value) if keys_only
+          map_child_data(child_hash, attr, format, instance, child_plan,
+                         child_options)
+        end
+      end
+
+      def extract_compiled_child_value(compiled_path, key, value)
+        case compiled_path
+        when :key then key
+        when :value then value
+        else value.dig(*compiled_path)
+        end
+      end
+
       def kv_serialize_plan(rule, attr, _instance)
         return nil if rule.delegate || rule.raw_mapping? || rule.root_mapping? ||
           rule.hash_mappings || rule.child_mappings ||
@@ -824,7 +1020,8 @@ partition = nil)
         generation = Lutaml::Model::GlobalContext.context_generation
         if @lutaml_walk_plans.nil? || @lutaml_walk_generation != generation ||
             @lutaml_walk_format != format
-          key = [model_class, lutaml_register, format, generation]
+          key = [model_class, lutaml_register, format, generation,
+                 @lutaml_mapping_override]
           @lutaml_walk_plans =
             (KV_WALK_PLANS[key] ||= build_walk_plans(format))
           @lutaml_walk_generation = generation
@@ -861,6 +1058,11 @@ partition = nil)
             plan ? :scalar : :interpretive
           end
 
+        if kind == :hash_map && attr
+          child = build_child_map_plan(format, rule, attr)
+          return WalkPlan.new(:hash_map, attr, valid, nil, nil, false, child)
+        end
+
         plan || WalkPlan.new(kind, attr, valid, nil, nil, false)
       end
 
@@ -979,14 +1181,20 @@ instance)
         child_mappings.values == [:key] && hash.values.all?(::Hash)
       end
 
-      def map_child_data(child_hash, attr, format, instance)
-        attr_type = attr.type(lutaml_register)
-        options = {
-          mappings: attr_type.mappings_for(format, lutaml_register),
-          lutaml_parent: instance,
-          lutaml_root: instance.lutaml_root || instance,
-        }
-        self.class.data_to_model(attr_type, child_hash, format, options)
+      def map_child_data(child_hash, attr, format, instance,
+child_plan = nil, child_options = nil)
+        if child_plan
+          self.class.data_to_model(child_plan.attr_type, child_hash, format,
+                                   child_options)
+        else
+          attr_type = attr.type(lutaml_register)
+          options = {
+            mappings: attr_type.mappings_for(format, lutaml_register),
+            lutaml_parent: instance,
+            lutaml_root: instance.lutaml_root || instance,
+          }
+          self.class.data_to_model(attr_type, child_hash, format, options)
+        end
       end
 
       def rule_value_extractor_class

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

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    # Raised when a `mapping:` selection names a serialization mapping
+    # profile the model does not declare (#176).
+    class UnknownMappingError < Error
+      def initialize(name, format)
+        dsl = format == :hash ? :hsh : format
+        super(
+          "unknown #{format} mapping profile #{name.inspect} — declare it " \
+          "with `#{dsl} :#{name} do ... end` or wire it with " \
+          "mapping :#{name}, mapping",
+        )
+      end
+    end
+  end
+end

data/lib/lutaml/model/schema/generator/property.rb

@@ -96,8 +96,35 @@ module Lutaml
           def get_constraints(attr)
             constraints = {}
 
-            # Add pattern validation
-            constraints["pattern"] = attr.pattern.source if attr.pattern
+            # Add pattern validation (attribute option conjunctive with the
+            # resolved type's restriction facets; a single JSON Schema
+            # pattern cannot express conjunction, mirroring the XSD emitter)
+            patterns = constraint_patterns(attr)
+            if patterns.size > 1
+              raise Lutaml::Model::Error,
+                    "Cannot export #{patterns.size} conjunctive patterns on " \
+                    "#{attr.name} to a single JSON Schema pattern: sibling " \
+                    "patterns are alternatives (OR), and JSON Schema cannot " \
+                    "express conjunction (AND) without allOf, which is not " \
+                    "yet supported."
+            end
+            # Attribute-option patterns export verbatim (author contract);
+            # type-facet patterns carry Ruby \A/\z anchoring, which ECMA
+            # regexes lack — express the full-match intent with ^...$.
+            if (pattern, from_facet = patterns.first)
+              constraints["pattern"] =
+                from_facet ? json_schema_pattern(pattern) : pattern.source
+            end
+
+            # Add the resolved type's restriction facets and format
+            type = attr.type(register)
+            if type.is_a?(Class) && type <= Lutaml::Model::Type::Value
+              facets = type.facets
+              constraints["minimum"] = facets[:min_inclusive] if facets[:min_inclusive]
+              constraints["maximum"] = facets[:max_inclusive] if facets[:max_inclusive]
+              constraints["exclusiveMinimum"] = facets[:min_exclusive] if facets[:min_exclusive]
+              constraints["exclusiveMaximum"] = facets[:max_exclusive] if facets[:max_exclusive]
+            end
 
             # Add default value
             resolved = attr.default_value(register, nil)
@@ -108,21 +135,45 @@ module Lutaml
             # Add enumeration values
             constraints["enum"] = attr.enum_values if attr.enum?
 
+            # Add the format keyword for types that declare one (e.g. the
+            # NIST Metaschema types: ipv4, ipv6, email, uri-reference)
+            format = type.json_schema_format if type.is_a?(Class) &&
+              type <= Lutaml::Model::Type::Value
+            constraints["format"] = format if format
+
             constraints
           end
 
+          def constraint_patterns(attr)
+            patterns = []
+            patterns << [attr.pattern, false] if attr.pattern
+            type = attr.type(register)
+            if type.is_a?(Class) && type <= Lutaml::Model::Type::Value
+              type.facets[:pattern].to_a.each { |re| patterns << [re, true] }
+            end
+            patterns
+          end
+
+          # JSON Schema (ECMA) regexes have no \A/\z; full-match intent is
+          # expressed with ^...$ anchoring (the NIST JSON forms do the same).
+          def json_schema_pattern(regexp)
+            source = regexp.source
+            source = source.delete_prefix('\\A').delete_suffix('\\z')
+            "^#{source}$"
+          end
+
           def polymorphic?(attr)
             Utils.present?(attr.options[:polymorphic])
           end
 
           def get_type(type)
-            {
-              Lutaml::Model::Type::String => "string",
-              Lutaml::Model::Type::Integer => "integer",
-              Lutaml::Model::Type::Boolean => "boolean",
-              Lutaml::Model::Type::Float => "number",
-              Lutaml::Model::Type::Hash => "object",
-            }[type] || "string" # Default to string for unknown types
+            return "integer" if type.is_a?(Class) && type <= Lutaml::Model::Type::Integer
+            return "boolean" if type.is_a?(Class) && type <= Lutaml::Model::Type::Boolean
+            return "number" if type.is_a?(Class) && type <= Lutaml::Model::Type::Float
+            return "number" if type.is_a?(Class) && type <= Lutaml::Model::Type::Decimal
+            return "object" if type.is_a?(Class) && type <= Lutaml::Model::Type::Hash
+
+            "string" # Strings and all other scalar types
           end
         end
       end

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

@@ -11,9 +11,16 @@ module Lutaml
         # Process mapping DSL for a format
         #
         # @param format [Symbol] The format (:xml, :json, etc.)
-        # @param args [Array] Additional arguments (e.g., mapping class for XML)
+        # @param args [Array] Optional profile name (Symbol/String) naming a
+        #   serialization mapping (#176); other arguments keep their
+        #   historical no-op behavior
         # @param block [Proc] The DSL block to evaluate
-        def process_mapping(format, *_args, &block)
+        def process_mapping(format, *args, &block)
+          name = args.first
+          if name.is_a?(::Symbol) || name.is_a?(::String)
+            return declare_serialization_mapping(format, name.to_sym, &block)
+          end
+
           klass = ::Lutaml::Model::Config.mappings_class_for(format)
           existing = mappings[format]
           mappings[format] = if existing.nil? || !existing.is_a?(klass)
@@ -30,6 +37,68 @@ module Lutaml
           post_process_mapping(format)
         end
 
+        # Declare a named serialization mapping (#176): a complete mapping
+        # for one format, selectable per call via `mapping:`. Re-declaring
+        # the same name replaces.
+        def declare_serialization_mapping(format, name, &block)
+          klass = ::Lutaml::Model::Config.mappings_class_for(format)
+          mapping = klass.new
+          mapping.instance_eval(&block)
+          mapping.finalize(self) if mapping.is_a?(Lutaml::Xml::Mapping)
+          post_process_mapping(format)
+          lutaml_named_mappings[format][name] = mapping
+        end
+
+        # Wire a runtime-constructed serialization mapping object under a
+        # name (#176). The format is inferred from the mapping's class;
+        # pass `format:` when the class does not identify one. `nil`
+        # mapping removes the name (requires `format:`).
+        def mapping(name, mapping_object, format: nil)
+          if mapping_object.nil?
+            raise ::ArgumentError, "removal requires format:" unless format
+
+            lutaml_named_mappings[format].delete(name)
+            return
+          end
+
+          format ||= format_of_mapping_object(mapping_object)
+          klass = ::Lutaml::Model::Config.mappings_class_for(format)
+          unless mapping_object.is_a?(klass)
+            raise ::ArgumentError,
+                  "mapping is a #{mapping_object.class} but the #{format} " \
+                  "mapping class is #{klass}"
+          end
+
+          lutaml_named_mappings[format][name] = mapping_object
+        end
+
+        # Named serialization mappings declared for a format (#176).
+        #
+        # @param format [Symbol] The format
+        # @return [Hash] name -> mapping (a shallow copy)
+        def serialization_mappings(format)
+          named = lutaml_named_mappings[format]
+          named ? named.dup : {}
+        end
+
+        def lutaml_named_mappings
+          @lutaml_named_mappings ||= ::Hash.new { |h, k| h[k] = {} }
+        end
+
+        # Resolve the `mapping:` selection option (#176) into the
+        # transform seam option the transforms already read. A user-level
+        # `mappings:` takes precedence; a nil `mapping:` selects the base
+        # mapping. Mutates and returns options.
+        def resolve_serialization_mapping_option(format, options)
+          return options unless options.is_a?(::Hash) && options.key?(:mapping)
+
+          selected = options.delete(:mapping)
+          return options if selected.nil? || options.key?(:mappings)
+
+          options[:mappings] = serialization_mapping_for(format, selected)
+          options
+        end
+
         # Hook for format-specific post-processing after mapping DSL evaluation.
         # XML overrides this to call check_sort_configs!.
         #
@@ -45,6 +114,8 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The deserialized model instance
         def from(format, data, options = {})
+          resolve_serialization_mapping_option(format, options)
+
           if format == :xml && Lutaml::Model::Config.instance.xml_plan_fast_path
             fast = xml_plan_fast_path(data, options)
             return fast if fast
@@ -223,6 +294,8 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The model instance
         def of(format, doc, options = {})
+          resolve_serialization_mapping_option(format, options)
+
           if doc.is_a?(Array) && !array_passthrough_format?(format)
             return doc.map { |item| send(:"of_#{format}", item) }
           end
@@ -280,6 +353,8 @@ module Lutaml
         #   is always preserved when available, regardless of this option.
         # @return [String] The serialized output
         def to(format, instance, options = {})
+          resolve_serialization_mapping_option(format, options)
+
           # The rescue sits on the parse block, not the method, so cache
           # store failures propagate instead of becoming InvalidFormatError.
           with_conversion_cache(:to, format, instance, options) do
@@ -355,6 +430,8 @@ module Lutaml
         # @param options [Hash] Additional options
         # @return [Object] The format-specific data structure
         def as(format, instance, options = {})
+          resolve_serialization_mapping_option(format, options)
+
           if instance.is_a?(Array)
             return instance.map { |item| public_send(:"as_#{format}", item) }
           end
@@ -458,8 +535,44 @@ module Lutaml
           end
         end
 
+        # Resolve a mapping selection (#176): a registered profile name
+        # or a mapping instance of the format, validated. Schema
+        # generation and other mapping consumers share this resolution.
+        #
+        # @param format [Symbol] The format
+        # @param selected [Symbol, String, Mapping] The selection
+        # @return [Mapping] The resolved mapping
+        def serialization_mapping_for(format, selected)
+          if selected.is_a?(::Symbol) || selected.is_a?(::String)
+            name = selected.to_sym
+            named = lutaml_named_mappings[format]
+            return named[name] if named.key?(name)
+
+            raise Lutaml::Model::UnknownMappingError.new(name, format)
+          end
+
+          klass = ::Lutaml::Model::Config.mappings_class_for(format)
+          return selected if selected.is_a?(klass)
+
+          raise ::ArgumentError,
+                "mapping must be a #{klass} or a registered profile " \
+                "name, got #{selected.class}"
+        end
+
         private
 
+        def format_of_mapping_object(mapping_object)
+          format = ::Lutaml::Model::FormatRegistry.formats.find do |f|
+            ::Lutaml::Model::FormatRegistry.mappings_class_for(f) ==
+              mapping_object.class
+          end
+          return format if format
+
+          raise ::ArgumentError,
+                "cannot infer the format of a #{mapping_object.class}; " \
+                "pass format:"
+        end
+
         # Resolve adapter class for a format operation.
         #
         # @param format [Symbol] the format name

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

@@ -29,11 +29,12 @@ module Lutaml
         # @param format [Symbol] The format (:xml, :json, :yaml, etc.)
         # @param register [Symbol, Register, nil] The register for type resolution
         # @return [Transformation, nil] The pre-compiled transformation, or nil if cycle detected
-        def transformation_for(format, register = nil)
+        def transformation_for(format, register = nil, mapping: nil)
           resolved_register = Lutaml::Model::Register.resolve_for_child(self,
                                                                         register)
-          TransformationRegistry.instance.get_or_build_transformation(self,
-                                                                      format, resolved_register)
+          TransformationRegistry.instance.get_or_build_transformation(
+            self, format, resolved_register, mapping: mapping
+          )
         end
 
         # Build a new transformation instance for the format