lutaml-model 0.8.126 → 0.8.128

data/lib/lutaml/model/transform.rb

@@ -11,18 +11,23 @@ module Lutaml
 
       def self.data_to_model(context, data, format, options = {})
         register = options[:register] || Lutaml::Model::Config.default_register
-        transform = cached_transform(context, register)
+        transform = cached_transform(context, register, options[:mappings])
         transform.data_to_model(data, format, options)
       end
 
       def self.model_to_data(context, model, format, options = {})
         register = model.lutaml_register if model.is_a?(Lutaml::Model::Serialize)
         register ||= Lutaml::Model::Config.default_register
-        transform = cached_transform(context, register)
+        transform = cached_transform(context, register, options[:mappings])
         transform.model_to_data(model, format, options)
       end
 
-      def self.cached_transform(context, register)
+      # An explicit mapping (#176 `mapping:` profiles / `mappings:` seam)
+      # gets a dedicated transform so per-instance compiled state (walk
+      # plans, serialize plans) never mixes with the base mapping's.
+      def self.cached_transform(context, register, mappings = nil)
+        return override_transform(context, register, mappings) if mappings
+
         @transform_cache ||= {}
         cache_key = [context, register]
         entry = @transform_cache[cache_key]
@@ -32,8 +37,25 @@ module Lutaml
         @transform_cache[cache_key] = new(context, register)
       end
 
+      def self.override_transform(context, register, mappings)
+        @override_transform_cache ||= {}
+        cache_key = [context, register, mappings.object_id]
+        entry = @override_transform_cache[cache_key]
+        return entry if entry
+
+        evict_override_if_needed if @override_transform_cache.size >= MAX_CACHE_SIZE
+        @override_transform_cache[cache_key] = new(context, register, mappings)
+      end
+
+      def self.evict_override_if_needed
+        keys = @override_transform_cache.keys.first(@override_transform_cache.size / 2)
+        keys.each { |k| @override_transform_cache.delete(k) }
+      end
+      private_class_method :evict_override_if_needed
+
       def self.clear_cache!
         @transform_cache&.clear
+        @override_transform_cache&.clear
       end
 
       def self.cache_size
@@ -59,9 +81,10 @@ module Lutaml
 
       attr_reader :context, :lutaml_register
 
-      def initialize(context, register = nil)
+      def initialize(context, register = nil, mappings_override = nil)
         @context = context
         @lutaml_register = register || Lutaml::Model::Config.default_register
+        @lutaml_mapping_override = mappings_override
       end
 
       def attributes
@@ -106,6 +129,8 @@ module Lutaml
       end
 
       def mappings_for(format, register = nil)
+        return @lutaml_mapping_override if @lutaml_mapping_override
+
         context.mappings_for(format, register)
       end
 

data/lib/lutaml/model/transformation_registry.rb

@@ -113,8 +113,9 @@ module Lutaml
       # @param format [Symbol] The format (:xml, :json, :yaml, :hash, :toml)
       # @param register [Symbol, Register, nil] The register for type resolution
       # @return [Transformation, nil] The transformation, or nil if cycle detected
-      def get_or_build_transformation(model_class, format, register)
-        key = transformation_key(model_class, format, register)
+      def get_or_build_transformation(model_class, format, register,
+                                      mapping: nil)
+        key = transformation_key(model_class, format, register, mapping)
         current_thread = Thread.current
 
         @mutex.synchronize do
@@ -144,7 +145,7 @@ module Lutaml
 
         # Build transformation OUTSIDE the lock to avoid deadlock
         # (building may trigger recursive calls to get_or_build_transformation)
-        mapping = get_or_build_mapping(model_class, format, register)
+        mapping ||= get_or_build_mapping(model_class, format, register)
         transformation = build_transformation(model_class, mapping, format,
                                               register)
 
@@ -221,7 +222,7 @@ module Lutaml
       # @param format [Symbol] The format
       # @param register [Symbol, Register, nil] The register
       # @return [Symbol] Unique cache key
-      def transformation_key(model_class, format, register)
+      def transformation_key(model_class, format, register, mapping = nil)
         register_id = extract_register_id(register)
         # Always include object_id to prevent cache pollution between classes
         # with the same name (common in test fixtures)
@@ -233,7 +234,8 @@ module Lutaml
                    else
                      "#{class_name}@0x#{model_class.object_id.to_s(16)}"
                    end
-        :"#{class_id}#{format}#{register_id}"
+        key = :"#{class_id}#{format}#{register_id}"
+        mapping ? :"#{key}#m#{mapping.object_id}" : key
       end
 
       # Build unique key for mapping cache

data/lib/lutaml/model/type/date_time_with_timezone.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema date-time-with-timezone datatype (#107): a
+      # date-time that must carry a UTC offset or Z.
+      #
+      # @example Using DateTimeWithTimezone type
+      #   attribute :generated_at, :date_time_with_timezone
+      class DateTimeWithTimezone < DateTime
+        TIMEZONE = /(Z|[+-]\d{2}:\d{2})\z/
+
+        def self.valid?(value)
+          value.is_a?(::String) ? value.match?(TIMEZONE) : !cast(value).nil?
+        end
+
+        def self.json_schema_format
+          "date-time"
+        end
+
+        def self.default_xsd_type
+          "xs:dateTime"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/date_with_timezone.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema date-with-timezone datatype (#107): a date that
+      # must carry a UTC offset or Z.
+      #
+      # @example Using DateWithTimezone type
+      #   attribute :effective_on, :date_with_timezone
+      class DateWithTimezone < Date
+        TIMEZONE = /(Z|[+-]\d{2}:\d{2})\z/
+
+        def self.valid?(value)
+          value.is_a?(::String) ? value.match?(TIMEZONE) : !cast(value).nil?
+        end
+
+        def self.json_schema_format
+          "date"
+        end
+
+        def self.default_xsd_type
+          "xs:date"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/day_time_duration.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema day-time-duration datatype (#107): an ISO 8601
+      # duration expressed in days, hours, minutes, and seconds (no
+      # years or months), per the xs:dayTimeDuration form. Built by
+      # interpolation with no formatting whitespace, so the pattern's
+      # source is export-clean for xs:pattern facets.
+      #
+      # @example Using DayTimeDuration type
+      #   attribute :elapsed, :day_time_duration
+      class DayTimeDuration < Duration
+        ELAPSED_TIME =
+          "(?:[0-9]+H(?:[0-9]+M)?(?:[0-9]+(?:\\.[0-9]+)?S)?" \
+          "|[0-9]+M(?:[0-9]+(?:\\.[0-9]+)?S)?" \
+          "|[0-9]+(?:\\.[0-9]+)?S)"
+        PATTERN = /\A-?P(?:[0-9]+D(?:T#{ELAPSED_TIME})?|T#{ELAPSED_TIME})\z/
+
+        def self.valid?(value)
+          value.is_a?(::String) ? value.match?(PATTERN) : !cast(value).nil?
+        end
+
+        def self.json_schema_format
+          "duration"
+        end
+
+        def self.default_xsd_type
+          "xs:dayTimeDuration"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/email_address.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema email-address datatype (#107): a string containing
+      # an at-sign, per the metaschema-datatypes pattern `.+@.+`.
+      #
+      # @example Using EmailAddress type
+      #   attribute :contact, :email_address
+      class EmailAddress < String
+        extend MetaschemaPattern
+
+        PATTERN = /\A.+@.+\z/
+
+        pattern PATTERN
+
+        def self.json_schema_format
+          "email"
+        end
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/hostname.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema hostname datatype (#107): a non-empty string with
+      # no outer whitespace. The normative XSD carries no hostname pattern
+      # yet (the metaschema spec notes it is pending), so only the
+      # trimmed-string base constraint applies.
+      #
+      # @example Using Hostname type
+      #   attribute :host, :hostname
+      class Hostname < String
+        extend MetaschemaPattern
+
+        PATTERN = /\A\S(.*\S)?\z/
+
+        pattern PATTERN
+
+        def self.json_schema_format
+          "idn-hostname"
+        end
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/ip_v4_address.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema ip-v4-address datatype (#107): dotted-quad IPv4
+      # per the metaschema-datatypes pattern.
+      #
+      # @example Using IpV4Address type
+      #   attribute :address, :ip_v4_address
+      class IpV4Address < String
+        extend MetaschemaPattern
+
+        OCTET = /(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])/
+        PATTERN = /\A#{OCTET.source}\.#{OCTET.source}\.#{OCTET.source}\.#{OCTET.source}\z/
+
+        def self.json_schema_format
+          "ipv4"
+        end
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/ip_v6_address.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema ip-v6-address datatype (#107): RFC3513 IPv6 text
+      # form, per the metaschema-datatypes pattern (the generalized
+      # StackOverflow IPv6 expression with metaschema customizations,
+      # including link-local zones and embedded IPv4). Built by
+      # interpolation with no formatting whitespace, so the pattern's
+      # source is export-clean for xs:pattern facets.
+      #
+      # @example Using IpV6Address type
+      #   attribute :address, :ip_v6_address
+      class IpV6Address < String
+        extend MetaschemaPattern
+
+        HEX4 = "[0-9a-fA-F]{1,4}"
+        OCTET = "(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])"
+        EMBEDDED_V4 = "(#{OCTET}\\.){3,3}#{OCTET}".freeze
+        GROUPS = "(#{HEX4}:){7,7}#{HEX4}" \
+                 "|([0-9a-fA-F]{1,4}:){1,7}:" \
+                 "|([0-9a-fA-F]{1,4}:){1,6}:#{HEX4}" \
+                 "|([0-9a-fA-F]{1,4}:){1,5}(:#{HEX4}){1,2}" \
+                 "|([0-9a-fA-F]{1,4}:){1,4}(:#{HEX4}){1,3}" \
+                 "|([0-9a-fA-F]{1,4}:){1,3}(:#{HEX4}){1,4}" \
+                 "|([0-9a-fA-F]{1,4}:){1,2}(:#{HEX4}){1,5}" \
+                 "|#{HEX4}:((:#{HEX4}){1,6})" \
+                 "|:((:#{HEX4}){1,7}|:)" \
+                 "|[fF][eE]80:(:[0-9a-fA-F]{0,4}){0,4}%[0-9a-zA-Z]{1,}" \
+                 "|::([fF]{4}(:0{1,4}){0,1}:){0,1}#{EMBEDDED_V4}" \
+                 "|([0-9a-fA-F]{1,4}:){1,4}:#{EMBEDDED_V4}".freeze
+        PATTERN = /\A(#{GROUPS})\z/
+
+        pattern PATTERN
+
+        def self.json_schema_format
+          "ipv6"
+        end
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/metaschema_pattern.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # Pattern machinery shared by the NIST Metaschema string types (#107).
+      # Each including class defines a PATTERN regexp (also declared as the
+      # type's `pattern` facet, feeding runtime validation and XSD
+      # restriction emission); values cast to strings and `valid?` checks
+      # full-match against it.
+      module MetaschemaPattern
+        def valid?(value)
+          return false if value.nil?
+
+          self::PATTERN.match?(value.to_s)
+        end
+
+        def cast(value, _options = {})
+          return nil if value.nil?
+          return value if Utils.uninitialized?(value)
+          return value if value.is_a?(::String)
+
+          value.to_s
+        end
+
+        def serialize(value)
+          return nil if value.nil?
+
+          value.to_s
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/non_negative_integer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema non-negative-integer datatype (#107): an integer
+      # equal to or greater than 0 (xs:nonNegativeInteger).
+      #
+      # @example Using NonNegativeInteger type
+      #   attribute :index, :non_negative_integer
+      class NonNegativeInteger < Integer
+        inclusive(min: 0)
+        def self.valid?(value)
+          cast_value = cast(value)
+
+          cast_value.is_a?(::Integer) && cast_value >= 0
+        end
+
+        def self.default_xsd_type
+          "xs:nonNegativeInteger"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/positive_integer.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema positive-integer datatype (#107): an integer
+      # greater than 0 (xs:positiveInteger).
+      #
+      # @example Using PositiveInteger type
+      #   attribute :ordinal, :positive_integer
+      class PositiveInteger < Integer
+        inclusive(min: 1)
+        def self.valid?(value)
+          cast_value = cast(value)
+
+          cast_value.is_a?(::Integer) && cast_value >= 1
+        end
+
+        def self.default_xsd_type
+          "xs:positiveInteger"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/token.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema token datatype (#107): an XML NMTOKEN-like value —
+      # a letter or underscore followed by letters, numbers, and the
+      # punctuation `.-_` — per the metaschema-datatypes pattern.
+      #
+      # @example Using Token type
+      #   attribute :label, :token
+      class Token < String
+        extend MetaschemaPattern
+
+        PATTERN = /\A(\p{L}|_)(\p{L}|\p{N}|[.\-_])*\z/
+
+        pattern PATTERN
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/uri_reference.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema uri-reference datatype (#107): a relative or
+      # absolute URI reference — any non-empty string without outer
+      # whitespace, unlike :uri which requires a scheme.
+      #
+      # @example Using UriReference type
+      #   attribute :link, :uri_reference
+      class UriReference < String
+        extend MetaschemaPattern
+
+        PATTERN = /\A\S(.*\S)?\z/
+
+        pattern PATTERN
+
+        def self.json_schema_format
+          "uri-reference"
+        end
+
+        def self.default_xsd_type
+          "xs:anyURI"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/uuid.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema uuid datatype (#107): an RFC4122 UUID, restricted
+      # to versions 4 and 5 and the standard variant, per the
+      # metaschema-datatypes pattern.
+      #
+      # @example Using Uuid type
+      #   attribute :identifier, :uuid
+      class Uuid < String
+        extend MetaschemaPattern
+
+        PATTERN = %r{\A[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[45][0-9A-Fa-f]{3}-[89ABab][0-9A-Fa-f]{3}-[0-9A-Fa-f]{12}\z}
+
+        pattern PATTERN
+
+        def self.default_xsd_type
+          "xs:string"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type/value.rb

@@ -126,6 +126,15 @@ from: nil)
                   "conflicting `#{key}` facets: #{existing} and #{incoming}"
           end
 
+          # The JSON Schema `format` keyword for this type, or nil. The NIST
+          # Metaschema types declare the format the metaschema JSON
+          # representations use (ipv4, ipv6, email, uri-reference, duration,
+          # date, date-time); core types default to nil and their schemas
+          # carry no format keyword.
+          def json_schema_format
+            nil
+          end
+
           # Constrain ordered values via min/maxInclusive.
           def inclusive(min: nil, max: nil)
             min = cast_facet_value(min)

data/lib/lutaml/model/type/year_month_duration.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Lutaml
+  module Model
+    module Type
+      # NIST Metaschema year-month-duration datatype (#107): an ISO 8601
+      # duration expressed in years and months (no time components), per
+      # the xs:yearMonthDuration form — P1Y6M, -P9M, P10M.
+      #
+      # @example Using YearMonthDuration type
+      #   attribute :term, :year_month_duration
+      class YearMonthDuration < Duration
+        PATTERN = /\A-?P(?:[0-9]+Y(?:[0-9]+M)?|[0-9]+M)\z/
+
+        def self.valid?(value)
+          value.is_a?(::String) ? value.match?(PATTERN) : !cast(value).nil?
+        end
+
+        def self.json_schema_format
+          "duration"
+        end
+
+        def self.default_xsd_type
+          "xs:yearMonthDuration"
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/model/type.rb

@@ -24,6 +24,20 @@ module Lutaml
       autoload :QName, "#{__dir__}/type/qname"
       autoload :Base64Binary, "#{__dir__}/type/base64_binary"
       autoload :HexBinary, "#{__dir__}/type/hex_binary"
+      autoload :MetaschemaPattern, "#{__dir__}/type/metaschema_pattern"
+      autoload :EmailAddress, "#{__dir__}/type/email_address"
+      autoload :Hostname, "#{__dir__}/type/hostname"
+      autoload :IpV4Address, "#{__dir__}/type/ip_v4_address"
+      autoload :IpV6Address, "#{__dir__}/type/ip_v6_address"
+      autoload :Token, "#{__dir__}/type/token"
+      autoload :UriReference, "#{__dir__}/type/uri_reference"
+      autoload :Uuid, "#{__dir__}/type/uuid"
+      autoload :NonNegativeInteger, "#{__dir__}/type/non_negative_integer"
+      autoload :PositiveInteger, "#{__dir__}/type/positive_integer"
+      autoload :DateWithTimezone, "#{__dir__}/type/date_with_timezone"
+      autoload :DateTimeWithTimezone, "#{__dir__}/type/date_time_with_timezone"
+      autoload :DayTimeDuration, "#{__dir__}/type/day_time_duration"
+      autoload :YearMonthDuration, "#{__dir__}/type/year_month_duration"
 
       # Error classes (defined in error/type/ but under Type namespace)
       autoload :InvalidValueError, "#{__dir__}/error/type/invalid_value_error"
@@ -55,6 +69,19 @@ module Lutaml
         qname: "Lutaml::Model::Type::QName",
         base64_binary: "Lutaml::Model::Type::Base64Binary",
         hex_binary: "Lutaml::Model::Type::HexBinary",
+        email_address: "Lutaml::Model::Type::EmailAddress",
+        hostname: "Lutaml::Model::Type::Hostname",
+        ip_v4_address: "Lutaml::Model::Type::IpV4Address",
+        ip_v6_address: "Lutaml::Model::Type::IpV6Address",
+        token: "Lutaml::Model::Type::Token",
+        uri_reference: "Lutaml::Model::Type::UriReference",
+        uuid: "Lutaml::Model::Type::Uuid",
+        non_negative_integer: "Lutaml::Model::Type::NonNegativeInteger",
+        positive_integer: "Lutaml::Model::Type::PositiveInteger",
+        date_with_timezone: "Lutaml::Model::Type::DateWithTimezone",
+        date_time_with_timezone: "Lutaml::Model::Type::DateTimeWithTimezone",
+        day_time_duration: "Lutaml::Model::Type::DayTimeDuration",
+        year_month_duration: "Lutaml::Model::Type::YearMonthDuration",
       }.freeze
 
       BUILTIN_CLASSES =

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.126"
+    VERSION = "0.8.128"
   end
 end

data/lib/lutaml/model.rb

@@ -164,6 +164,8 @@ module Lutaml
              "#{__dir__}/model/error/import_model_with_root_error"
     autoload :UnsupportedVersionError,
              "#{__dir__}/model/error/unsupported_version_error"
+    autoload :UnknownMappingError,
+             "#{__dir__}/model/error/unknown_mapping_error"
     autoload :InvalidChoiceRangeError,
              "#{__dir__}/model/error/invalid_choice_range_error"
     autoload :UnknownSequenceMappingError,

data/lib/lutaml/xml/adapter/xml_serializer.rb

@@ -144,18 +144,19 @@ module Lutaml
           return root if root.is_a?(Lutaml::Xml::DataModel::XmlElement)
 
           mapper_class = options[:mapper_class] || root.class
-          xml_mapping = mapper_class.mappings_for(:xml)
+          xml_mapping = options[:mappings] || mapper_class.mappings_for(:xml)
 
           return nil if xml_mapping.raw_mapping&.custom_methods&.[](:to)
 
           yield(root)
-          mapper_class.transformation_for(:xml, register).transform(root,
-                                                                    options)
+          mapper_class.transformation_for(
+            :xml, register, mapping: options[:mappings]
+          ).transform(root, options)
         end
 
         def render_xml_element(xml, xml_element, original_model, options)
           mapper_class = options[:mapper_class] || xml_element.class
-          mapping = mapper_class.mappings_for(:xml)
+          mapping = options[:mappings] || mapper_class.mappings_for(:xml)
           plan = declaration_plan_for(
             xml_element,
             mapping,
@@ -171,7 +172,7 @@ module Lutaml
 
         def render_legacy_model(xml, options)
           mapper_class = options[:mapper_class] || root.class
-          xml_mapping = mapper_class.mappings_for(:xml)
+          xml_mapping = options[:mappings] || mapper_class.mappings_for(:xml)
           plan = declaration_plan_for(root, xml_mapping, options, mapper_class)
 
           build_element_with_plan(xml, root, plan, options)
@@ -191,7 +192,8 @@ module Lutaml
           stored_plan = nil
 
           if original_model
-            mapping_for_original = options[:mapper_class]&.mappings_for(:xml) ||
+            mapping_for_original = options[:mappings] ||
+              options[:mapper_class]&.mappings_for(:xml) ||
               original_model.class.mappings_for(:xml)
             original_ns_uris = collect_original_namespace_uris(
               original_model, mapping_for_original