lutaml-model 0.8.125 → 0.8.127

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd52cd1acd33af2b1f8abe39a9d57c4412618d63ee65b516204ef4fa9f7ff047
-  data.tar.gz: 903e6d8ed42b95b0c5f79616f362d856b79ef54c90b3bbc1ba854c3345e79bd2
+  metadata.gz: e11de7c2a53b5c720a4d8066af0a1b0bfef2107e6c853bfb441d478b32c0d794
+  data.tar.gz: 6f8e67b8df0ab6ee2635b3b2c83a7dc86332e7883d951df45f8422f303b1ca61
 SHA512:
-  metadata.gz: 125f630b5d0816ad0dbbf98e1650f9a221a19c83793fe05c38e384fa884ec251774e97b0ce9636be1a014f84f678fc2c4d42d9cbea108fc615051fbd1bf4112c
-  data.tar.gz: 9eec80327bca08b7cc3bb649c77c1b956356baa190d434ae86c5eebacaacfda95c5e2ed2392d6c1d2db7a98fa4a7e32d6d416eb74185d5f0ba8ba416cef66d2a
+  metadata.gz: 447cbac13172eab2c4fcfa38f03f6777a164dfd31108e9aa3ce46ca8eed631863c9bd584f88a83dae005d80836c6be5ee4ff046676a77492a8c52f509b2cb4e8
+  data.tar.gz: 7b13afe6b4d08b89b4e79143599ac90da0fb6536583f8e315e829f66a6579e6fd22ed8aa87acc46359e06741eada456f7e5ee97db897df5e172fbcb4c43705db

data/README.adoc

@@ -830,6 +830,19 @@ Every type has a corresponding Ruby class and a serialization format type.
 | `:qname`              | `Lutaml::Model::Type::QName` | `xs:QName`    | `string`  | `string`  | `"prefix:localName"`
 | `:base64_binary`      | `String`                 | `xs:base64Binary` | `string`  | `string`  | `"SGVsbG8gV29ybGQ="`
 | `:hex_binary`         | `String`                 | `xs:hexBinary`    | `string`  | `string`  | `"48656c6c6f"`
+| `:email_address`      | `String`                 | `xs:string`       | `string`  | `string`  | `"user@example.com"`
+| `:hostname`           | `String`                 | `xs:string`       | `string`  | `string`  | `"example.com"`
+| `:ip_v4_address`      | `String`                 | `xs:string`       | `string`  | `string`  | `"192.168.0.1"`
+| `:ip_v6_address`      | `String`                 | `xs:string`       | `string`  | `string`  | `"2001:db8::2:1"`
+| `:token`              | `String`                 | `xs:string`       | `string`  | `string`  | `"label_3.v2"`
+| `:uri_reference`      | `String`                 | `xs:anyURI`       | `string`  | `string`  | `"path/to/resource"`
+| `:uuid`               | `String`                 | `xs:string`       | `string`  | `string`  | `"a3bb189e-8bf9-4888-9912-ace4e6543002"`
+| `:non_negative_integer` | `Integer`              | `xs:nonNegativeInteger` | `number` | `integer` | `7`
+| `:positive_integer`   | `Integer`                | `xs:positiveInteger` | `number` | `integer` | `7`
+| `:date_with_timezone` | `Date`/`DateTime`        | `xs:date`         | `string`  | `string`  | `"2019-12-02-08:00"`
+| `:date_time_with_timezone` | `DateTime`         | `xs:dateTime`     | `string`  | `string`  | `"2019-12-02T16:39:57-08:00"`
+| `:day_time_duration`  | `Lutaml::Model::Type::Duration` | `xs:dayTimeDuration` | `string` | `string` | `"P1DT12H45M"`
+| `:year_month_duration` | `Lutaml::Model::Type::Duration` | `xs:yearMonthDuration` | `string` | `string` | `"P1Y6M"`
 | `:hash`               | `Hash`                   | complex element   | object    | map       | `{key: "value"}`
 | (nil value)           | `nil`                    | `xs:anyType`      | `null`    | `null`    | `null`
 | `{ ref: [Model, :attr] }` | `Reference`          | `xs:string`       | `string`  | `string`  | `"model-id"`
@@ -840,6 +853,45 @@ Every type has a corresponding Ruby class and a serialization format type.
 |===
 
 
+=== NIST Metaschema types
+
+The NIST Metaschema simple data types are supported as first-class value
+types (https://pages.nist.gov/metaschema/specification/datatypes/). Each
+type carries the normative metaschema-datatypes pattern and answers
+`valid?` for a value; casting follows the lenient base-type behavior.
+
+.Source types
+[cols="3,4,2"]
+|===
+| Type code        | Metaschema datatype  | Restriction
+
+| `:email_address` | `email-address`      | contains an at-sign
+| `:hostname`      | `hostname`           | non-empty, trimmed
+| `:ip_v4_address` | `ip-v4-address`      | dotted-quad IPv4
+| `:ip_v6_address` | `ip-v6-address`      | RFC3513 IPv6 (incl. zones, embedded IPv4)
+| `:token`         | `token`              | NMTOKEN-like letter/number/punctuation run
+| `:uri_reference` | `uri-reference`      | relative or absolute URI reference
+| `:uuid`          | `uuid`               | RFC4122 UUID, version 4 or 5
+| `:non_negative_integer` | `non-negative-integer` | integer >= 0
+| `:positive_integer` | `positive-integer` | integer >= 1
+| `:date_with_timezone` | `date-with-timezone` | date with `Z` or offset
+| `:date_time_with_timezone` | `date-time-with-timezone` | date-time with `Z` or offset
+| `:day_time_duration` | `day-time-duration` | duration without years/months
+| `:year_month_duration` | `year-month-duration` | duration without time components
+|===
+
+.Usage
+[source,ruby]
+----
+class Asset < Lutaml::Model::Serializable
+  attribute :id, :uuid
+  attribute :owner, :email_address
+  attribute :host, :hostname
+  attribute :address, :ip_v4_address
+  attribute :renewal, :year_month_duration
+end
+----
+
 === Decimal type
 
 The Decimal type uses Ruby's `BigDecimal` for arbitrary-precision decimal

data/docs/_guides/keyvalue-serialization.adoc

@@ -1188,3 +1188,78 @@ In this example:
 `name` attributes, respectively.
 ====
 
+
+== Serialization mapping profiles
+
+A model can declare multiple serialization mappings for the same format —
+*serialization mapping profiles* (also called projections or lenses). Each
+profile is a complete mapping: what it maps is the projection, and
+anything it does not map stays outside it. The base mapping (declared
+without a name) remains the default.
+
+=== Declaring a profile
+
+[source,ruby]
+----
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :email, :string
+  attribute :internal_id, :string
+
+  json do
+    map "name", to: :name
+    map "email", to: :email
+    map "internal_id", to: :internal_id
+  end
+
+  json :compact do
+    map "name", to: :name
+  end
+end
+----
+
+=== Selecting a profile
+
+Profiles are selected per call with the `mapping:` option, for both
+serialization and parsing. An unknown profile name raises
+`Lutaml::Model::UnknownMappingError`.
+
+[source,ruby]
+----
+person.to_json                       # => {"name"=>"Ed", ...}
+person.to_json(mapping: :compact)    # => {"name"=>"Ed"}
+Person.from_json(json, mapping: :compact)
+----
+
+`only:` and `except:` compose with the selected profile. Child models
+always serialize through their own mappings; a parent's profile does not
+propagate to them.
+
+=== Runtime-constructed mappings
+
+A mapping object can be built at runtime and wired to the model, or used
+directly for a single call. This supports projections that are not known
+at class-definition time.
+
+[source,ruby]
+----
+mapping = Lutaml::Model::Config.mappings_class_for(:yaml).new
+mapping.map "full_name", to: :name
+
+Person.mapping :public, mapping   # register as a named profile
+person.to_yaml(mapping: :public)  # by name
+
+person.to_yaml(mapping: mapping)  # ephemeral, unwired single use
+----
+
+`Person.mapping :name, nil, format: :yaml` removes a registered profile.
+`Person.serialization_mappings(:yaml)` returns the registered profiles of
+a format. Re-declaring or re-registering a name replaces the previous
+mapping.
+
+XML profiles follow the same shape: `xml :registry do ... end` declares a
+profile with its own root element, and `to_xml(mapping: :registry)` /
+`from_xml(data, mapping: :registry)` select it. XSD generation honors
+the selection too: `Lutaml::Model::Schema.to_xsd(Record, mapping:
+:registry)` generates the schema of that projection, leaving unmapped
+attributes outside it.

data/lib/compat/opal/lutaml_model_boot.rb

@@ -281,6 +281,7 @@ require "lutaml/model/error/undefined_attribute_error"
 require "lutaml/model/error/union_schema_unsupported_error"
 require "lutaml/model/error/unknown_adapter_type_error"
 require "lutaml/model/error/unknown_discriminator_error"
+require "lutaml/model/error/unknown_mapping_error"
 require "lutaml/model/error/unknown_sequence_mapping_error"
 require "lutaml/model/error/unknown_type_error"
 require "lutaml/model/error/unresolvable_type_error"
@@ -333,21 +334,35 @@ require "lutaml/model/type/base64_binary"
 require "lutaml/model/type/boolean"
 require "lutaml/model/type/date"
 require "lutaml/model/type/date_time"
+require "lutaml/model/type/date_time_with_timezone"
+require "lutaml/model/type/date_with_timezone"
+require "lutaml/model/type/day_time_duration"
 require "lutaml/model/type/decimal"
 require "lutaml/model/type/duration"
+require "lutaml/model/type/email_address"
 require "lutaml/model/type/float"
 require "lutaml/model/type/hash"
 require "lutaml/model/type/hex_binary"
+require "lutaml/model/type/hostname"
 require "lutaml/model/type/integer"
+require "lutaml/model/type/ip_v4_address"
+require "lutaml/model/type/ip_v6_address"
+require "lutaml/model/type/metaschema_pattern"
+require "lutaml/model/type/non_negative_integer"
+require "lutaml/model/type/positive_integer"
 require "lutaml/model/type/qname"
 require "lutaml/model/type/reference"
 require "lutaml/model/type/string"
 require "lutaml/model/type/symbol"
 require "lutaml/model/type/time"
 require "lutaml/model/type/time_without_date"
+require "lutaml/model/type/token"
 require "lutaml/model/type/uninitialized_class_guard"
 require "lutaml/model/type/uri"
+require "lutaml/model/type/uri_reference"
+require "lutaml/model/type/uuid"
 require "lutaml/model/type/value"
+require "lutaml/model/type/year_month_duration"
 require "lutaml/rdf/namespaces/dcterms_namespace"
 require "lutaml/rdf/namespaces/owl_namespace"
 require "lutaml/rdf/namespaces/rdf_namespace"

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
@@ -475,12 +477,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 +512,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 +529,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 +772,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 +812,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 +912,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 +950,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 +1073,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/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