lutaml-model 0.8.10 → 0.8.12

data/docs/_guides/turtle-serialization.adoc

@@ -73,9 +73,18 @@ Member models (serialized via a container's `members` declaration) can omit the
 
 === type
 
-Sets the RDF type (`rdf:type`) triple. Compact IRIs (e.g., `"skos:Concept"`)
-are resolved to full URIs via the declared namespaces. Full URIs (e.g.,
-`"http://example.org/MyType"`) are used as-is.
+Sets the RDF type (`rdf:type`) triple. Accepts a single compact IRI or an array:
+
+[source,ruby]
+----
+type "skos:Concept"
+# or multiple types:
+type ["skos:Concept", "dcterms:Agent"]
+----
+
+Compact IRIs are resolved to full URIs via the declared namespaces. Full URIs
+(e.g., `"http://example.org/MyType"`) are used as-is. Each type produces a
+separate `a` triple in the output.
 
 === predicate
 
@@ -85,7 +94,11 @@ Each `predicate` creates a `Lutaml::Rdf::MappingRule` value object:
 * `namespace:` — the `Lutaml::Rdf::Namespace` subclass (required, validated)
 * `to:` — the model attribute to read/write (required)
 * `lang_tagged:` (default: `false`) — if true, appends `@lang` suffix from the
-  value's `language_code` or `language` method
+  value's `language_code` or `language` method. Mutually exclusive with
+  `uri_reference`.
+* `uri_reference:` (default: `false`) — if true, serializes values as URI
+  objects rather than string literals. Compact IRIs are resolved via the
+  declared namespaces. Mutually exclusive with `lang_tagged`.
 
 Validation errors:
 

data/docs/_guides/xml_mappings/07_best_practices.adoc

@@ -723,7 +723,8 @@ end
 
 * **Ox**: Fastest, use for performance-critical applications
 * **Nokogiri**: Most compatible, good balance
-* **Oga**: Pure Ruby, works with Opal, use when no native extensions allowed
+* **Oga**: Pure Ruby, use when no native extensions allowed
+* **REXML**: Pure Ruby (bundled with Ruby), Opal-compatible
 
 **Configure once:**
 

data/docs/_pages/configuration.adoc

@@ -74,7 +74,7 @@ When an adapter is needed for a format, `AdapterResolver` follows this chain:
 | Pure Ruby. No compilation needed. Opal-compatible.
 
 | `:rexml`
-| Pure Ruby. Bundled with Ruby (default gem).
+| Pure Ruby. Bundled with Ruby (default gem). Opal-compatible.
 |===
 
 === JSON adapters
@@ -261,8 +261,8 @@ end
 
 * **Nokogiri**: Most projects (default, best compatibility)
 * **Ox**: Performance-critical applications
-* **Oga**: Pure Ruby environments, Opal/JavaScript compilation
-* **REXML**: No extra gems, pure Ruby (bundled with Ruby)
+* **Oga**: Pure Ruby environments
+* **REXML**: No extra gems, pure Ruby (bundled with Ruby). Also used under Opal.
 
 === Choose JSON adapter based on
 
@@ -279,12 +279,14 @@ end
 
 Lutaml::Model supports running under https://opalrb.com[Opal] (Ruby compiled to JavaScript) with some limitations. The library detects the runtime automatically via `Lutaml::Model::RuntimeCompatibility` and adapts its behavior accordingly.
 
+The XML parsing layer is provided by the https://github.com/lutaml/moxml[moxml] gem, which has been updated to support Opal. Under Opal, moxml uses the REXML adapter because Opal reimplements `strscan` and `stringio` in its stdlib, enabling REXML (pure Ruby) to compile cleanly to JavaScript.
+
 === Adapter defaults on Opal
 
 [cols="1,2",options="header"]
 |===
 | Format | Behavior
-| XML | Only `:oga` is available (auto-selected). Nokogiri, Ox, and REXML require native extensions.
+| XML | Only `:rexml` is available (auto-selected). Opal reimplements strscan/stringio in its stdlib, enabling REXML to compile to JavaScript.
 | JSON | Only `:standard` is available. Oj and MultiJson require native extensions.
 | YAML | `:standard` (Psych ships with Opal's stdlib).
 | TOML | **Not available.** Both tomlib and toml-rb depend on native extensions.
@@ -299,6 +301,9 @@ The following features raise `NotImplementedError` when called under Opal:
 * `Lutaml::Model::Schema.to_relaxng` -- RELAX NG generation requires Nokogiri
 * `Lutaml::Model::Schema.from_xml` -- XML schema compilation is not supported
 * `Lutaml::Xml::Schema::Xsd::Base#to_formatted_xml` -- XSD formatted output requires the Canon gem
+* XPath queries -- REXML XPath requires features not yet supported by Opal's stdlib
+
+See the link:../guides/opal[Opal Usage Guide] for complete setup instructions and limitations.
 
 == See also
 

data/docs/_pages/index.adoc

@@ -22,6 +22,7 @@ Fundamental concepts, configuration, and essential features of Lutaml::Model.
 * link:breaking-changes[Breaking Changes] - Version compatibility
 * link:comparison-with-shale[Comparison with Shale] - Migration guide
 * link:xml-conformance[XML Standards Conformance] - W3C spec compliance status
+* link:../guides/opal[Opal Usage] - Run in the browser via Opal
 * link:troubleshooting[Troubleshooting] - Common issues and solutions
 
 == Getting started

data/docs/_pages/serialization_adapters.adoc

@@ -192,8 +192,7 @@ Requires the `nokogiri` gem.
 Oga::
 (optional)
 Pure Ruby XML parser.
-Does not require native extensions and is suitable for
-https://opalrb.com[Opal] (Ruby on JavaScript).
+Does not require native extensions.
 Requires the `oga` gem.
 
 Ox::
@@ -206,6 +205,8 @@ REXML::
 (optional)
 Pure Ruby XML parser, bundled as a default gem with Ruby.
 Moved from standard library to a default gem in Ruby 3.0.
+Opal-compatible: Opal reimplements `strscan` and `stringio` in its stdlib,
+enabling REXML to compile cleanly to JavaScript.
 Requires the `rexml` gem (bundled with Ruby by default).
 
 

data/docs/index.adoc

@@ -19,6 +19,7 @@ Lutaml::Model is a Ruby library for creating information models with attributes
 * **Multi-format serialization** - XML, JSON, YAML, TOML, JSON-LD, Turtle, Hash, YAML Stream
 * **XML namespace support** - Full W3C namespace implementation
 * **Linked Data support** - RDF namespaces, JSON-LD, and Turtle serialization
+* **Opal support** - Run in the browser via Opal (Ruby to JavaScript) with REXML adapter
 * **Validation** - Built-in validation with custom rules
 * **Schema generation** - Generate XSD, JSON Schema, YAML Schema
 * **Polymorphism** - Handle multiple types elegantly

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

@@ -8,10 +8,8 @@ module Lutaml
           super(:hash)
         end
 
-        def deep_dup
-          self.class.new.tap do |new_mapping|
-            new_mapping.mappings = duplicate_mappings
-          end
+        def dup_instance
+          self.class.new
         end
       end
     end

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

@@ -8,10 +8,8 @@ module Lutaml
           super(:json)
         end
 
-        def deep_dup
-          self.class.new.tap do |new_mapping|
-            new_mapping.mappings = duplicate_mappings
-          end
+        def dup_instance
+          self.class.new
         end
       end
     end

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

@@ -8,10 +8,8 @@ module Lutaml
           super(:jsonl)
         end
 
-        def deep_dup
-          self.class.new.tap do |new_mapping|
-            new_mapping.mappings = duplicate_mappings
-          end
+        def dup_instance
+          self.class.new
         end
       end
     end

data/lib/lutaml/jsonld/transform.rb

@@ -35,7 +35,7 @@ module Lutaml
           value = hash[rule.predicate_name]
           next if value.nil?
 
-          attrs[rule.to] = if rule.lang_tagged && value.is_a?(Hash)
+          attrs[rule.to] = if rule.kind == :lang_tagged && value.is_a?(Hash)
                              flatten_language_map(value)
                            else
                              value
@@ -61,9 +61,8 @@ module Lutaml
         end
 
         mapping.rdf_members.each do |member_rule|
-          collection = Array(instance.public_send(member_rule.attr_name))
-          collection.each do |member|
-            member_mapping = member.class.mappings[:jsonld]
+          each_member(instance, member_rule) do |member|
+            member_mapping = member_mapping_for(member, :jsonld)
             next unless member_mapping
 
             resource = build_resource_data(member_mapping, member)
@@ -78,13 +77,12 @@ module Lutaml
         context_hash = build_context_from_mapping(mapping).to_hash
 
         mapping.rdf_members.each do |member_rule|
-          collection = Array(instance.public_send(member_rule.attr_name))
-          next if collection.empty?
-
-          member_mapping = collection.first.class.mappings[:jsonld]
-          next unless member_mapping
+          each_member(instance, member_rule) do |member|
+            member_mapping = member_mapping_for(member, :jsonld)
+            next unless member_mapping
 
-          context_hash.merge!(build_context_from_mapping(member_mapping).to_hash)
+            context_hash.merge!(build_context_from_mapping(member_mapping).to_hash)
+          end
         end
 
         context_hash
@@ -94,17 +92,30 @@ module Lutaml
         context = Context.new
         mapping.namespace_set.each { |ns| context.prefix(ns) }
         mapping.rdf_predicates.each do |pred|
-          if pred.lang_tagged
-            context.term(pred.predicate_name,
-                         id: pred.uri,
-                         container: :language)
-          else
-            context.term(pred.predicate_name, id: pred.uri)
-          end
+          options = { id: pred.uri }
+          term_options = context_term_options(pred)
+          context.term(pred.predicate_name, **options, **term_options)
         end
+
+        mapping.rdf_members.each do |member_rule|
+          next unless member_rule.linked?
+
+          context.term(member_rule.predicate_name.to_s,
+                       id: member_rule.linked_predicate_uri,
+                       type: "@id")
+        end
+
         context
       end
 
+      def context_term_options(rule)
+        case rule.kind
+        when :uri_reference then { type: "@id" }
+        when :lang_tagged then { container: :language }
+        else {}
+        end
+      end
+
       def build_resource_object(mapping, instance)
         context = build_context_from_mapping(mapping).to_hash
         data = build_resource_data(mapping, instance)
@@ -114,8 +125,12 @@ module Lutaml
       def build_resource_data(mapping, instance)
         result = {}
 
-        if mapping.rdf_type
-          result["@type"] = resolve_type_compact(mapping)
+        if mapping.rdf_type.any?
+          result["@type"] = if mapping.rdf_type.length == 1
+                              mapping.rdf_type.first
+                            else
+                              mapping.rdf_type
+                            end
         end
 
         if mapping.rdf_subject
@@ -127,16 +142,47 @@ module Lutaml
           next if value.nil?
           next if value.is_a?(String) && value.empty?
 
-          result[rule.predicate_name] = if rule.lang_tagged
-                                          build_language_map(value)
-                                        else
-                                          serialize_rdf_value(value)
-                                        end
+          result[rule.predicate_name] = serialize_value(value, rule)
+        end
+
+        mapping.rdf_members.each do |member_rule|
+          next unless member_rule.linked?
+
+          member_refs = collect_member_references(instance, member_rule)
+          next if member_refs.empty?
+
+          result[member_rule.predicate_name.to_s] = member_refs
         end
 
         result
       end
 
+      def collect_member_references(instance, member_rule)
+        refs = []
+        each_member(instance, member_rule) do |member|
+          member_mapping = member_mapping_for(member, :jsonld)
+          next unless member_mapping
+
+          refs << { "@id" => resolve_subject_uri(member_mapping, member) }
+        end
+        refs
+      end
+
+      def serialize_value(value, rule)
+        case rule.kind
+        when :uri_reference then serialize_uri_reference(value)
+        when :lang_tagged then build_language_map(value)
+        else serialize_rdf_value(value)
+        end
+      end
+
+      def serialize_uri_reference(value)
+        case value
+        when Array then value.map { |v| { "@id" => v.to_s } }
+        else { "@id" => value.to_s }
+        end
+      end
+
       def build_language_map(values)
         case values
         when Array

data/lib/lutaml/key_value/adapter/hash/mapping.rb

@@ -7,10 +7,8 @@ module Lutaml
             super(:hash)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/adapter/json/mapping.rb

@@ -12,10 +12,8 @@ module Lutaml
             super(:json)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/adapter/jsonl/mapping.rb

@@ -7,10 +7,8 @@ module Lutaml
             super(:jsonl)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/adapter/toml/mapping.rb

@@ -7,10 +7,8 @@ module Lutaml
             super(:toml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
 
           def validate!(key, to, with, render_nil, render_empty)

data/lib/lutaml/key_value/adapter/yaml/mapping.rb

@@ -7,10 +7,8 @@ module Lutaml
             super(:yaml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

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

@@ -7,10 +7,8 @@ module Lutaml
             super(:yaml)
           end
 
-          def deep_dup
-            self.class.new.tap do |new_mapping|
-              new_mapping.mappings = duplicate_mappings
-            end
+          def dup_instance
+            self.class.new
           end
         end
       end

data/lib/lutaml/key_value/mapping.rb

@@ -218,17 +218,17 @@ module Lutaml
       end
 
       # Writers for deep_dup in subclasses
-      attr_writer :mappings, :register_mappings
+      attr_writer :register_mappings
 
       def deep_dup
-        self.class.new(@format).tap do |new_mapping|
+        dup_instance.tap do |new_mapping|
           new_mapping.mappings = duplicate_mappings
           new_mapping.register_mappings = Lutaml::Model::Utils.deep_dup(@register_mappings)
         end
       end
 
-      def duplicate_mappings
-        Lutaml::Model::Utils.deep_dup(@mappings)
+      def dup_instance
+        self.class.new(@format)
       end
 
       def find_by_to(to)

data/lib/lutaml/model/adapter_resolver.rb

@@ -370,15 +370,12 @@ module Lutaml
 
         # Detect available XML adapter.
         #
-        # @return [Symbol, nil] :nokogiri, :ox, :oga, :rexml, or nil
+        # Delegates to moxml which is the authority on XML adapter
+        # availability and platform constraints (Opal, MRI, etc.).
+        #
+        # @return [Symbol] adapter type name
         def detect_xml_adapter
-          return :oga if RuntimeCompatibility.opal?
-          return :nokogiri if Utils.safe_load("nokogiri", :Nokogiri)
-          return :ox if Utils.safe_load("ox", :Ox)
-          return :oga if Utils.safe_load("oga", :Oga)
-          return :rexml if Utils.safe_load("rexml", :REXML)
-
-          nil
+          Moxml::Config.runtime_default_adapter
         end
 
         # Detect available TOML adapter.

data/lib/lutaml/model/mapping/mapping.rb

@@ -3,6 +3,8 @@ module Lutaml
     class Mapping
       include DeepDupable
 
+      attr_writer :mappings
+
       def initialize
         @mappings = []
         @listeners = {} # target => [Listener, ...]
@@ -11,6 +13,16 @@ module Lutaml
         @mappings_imported = ::Hash.new { |h, k| h[k] = false }
       end
 
+      def deep_dup
+        duped = self.class.new
+        duped.mappings = duplicate_mappings
+        duped
+      end
+
+      def duplicate_mappings
+        Lutaml::Model::Utils.deep_dup(@mappings)
+      end
+
       # Get listeners for a specific target (element name/key).
       #
       # @param target [String, Symbol] The element name or key

data/lib/lutaml/model/store.rb

@@ -5,9 +5,15 @@ require "weakref"
 module Lutaml
   module Model
     class Store
-      # Compact dead WeakRef shells after this many entries per class bucket.
+      # Compact dead WeakRef shells once a class bucket grows past this size.
       COMPACTION_THRESHOLD = 1000
 
+      # Once the threshold is exceeded, only compact every Nth subsequent
+      # register call. Amortises the O(N) reject! over N inserts so
+      # register stays O(1) per call rather than O(N) per call (O(N^2)
+      # cumulatively for the class).
+      COMPACTION_INTERVAL = 1000
+
       class << self
         def instance
           @instance ||= new
@@ -39,14 +45,17 @@ module Lutaml
         # Nested index: { model_key => { reference_key => { value => WeakRef(object) } } }
         # Grouped by model_key so register only iterates this class's own indices.
         @index = {}
+        @inserts_since_compaction = ::Hash.new(0)
+        @compaction_count = 0
       end
 
       def register(object)
         model_key = object.class.to_s
         refs = @store[model_key]
         refs << WeakRef.new(object)
+        @inserts_since_compaction[model_key] += 1
 
-        compact_if_needed(refs)
+        compact_if_needed(refs, model_key)
 
         update_existing_indices(object, model_key)
       end
@@ -63,12 +72,16 @@ module Lutaml
         entry = model_indices[reference_key][reference_value]
         return nil unless entry
 
-        dereference(entry)
+        obj = dereference(entry)
+        model_indices[reference_key].delete(reference_value) unless obj
+        obj
       end
 
       def clear
         @store = ::Hash.new { |hash, key| hash[key] = [] }
         @index = {}
+        @inserts_since_compaction = ::Hash.new(0)
+        @compaction_count = 0
       end
 
       def store
@@ -81,6 +94,22 @@ module Lutaml
         end
       end
 
+      def refs_for(model_key)
+        @store[model_key]
+      end
+
+      def inserts_since_compaction
+        @inserts_since_compaction
+      end
+
+      def compaction_count
+        @compaction_count
+      end
+
+      def index_entry_count(model_key)
+        @index[model_key]&.sum { |_reference_key, entries| entries.size } || 0
+      end
+
       private
 
       def ensure_model_index(model_key)
@@ -120,14 +149,32 @@ module Lutaml
         nil
       end
 
-      def compact_if_needed(refs)
+      def compact_if_needed(refs, model_key)
         return unless refs.size > COMPACTION_THRESHOLD
+        return unless @inserts_since_compaction[model_key] >= COMPACTION_INTERVAL
 
+        @inserts_since_compaction[model_key] = 0
+        @compaction_count += 1
         refs.reject! do |ref|
           !ref.weakref_alive?
         rescue WeakRef::RefError
           true
         end
+        prune_index(model_key)
+      end
+
+      def prune_index(model_key)
+        model_indices = @index[model_key]
+        return unless model_indices
+
+        model_indices.delete_if do |_reference_key, entries|
+          entries.delete_if do |_value, ref|
+            !ref.weakref_alive?
+          rescue WeakRef::RefError
+            true
+          end
+          entries.empty?
+        end
       end
     end
   end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.10"
+    VERSION = "0.8.12"
   end
 end

data/lib/lutaml/rdf/mapping.rb

@@ -10,7 +10,7 @@ module Lutaml
         super
         @namespace_set = Lutaml::Rdf::NamespaceSet.new
         @rdf_subject = nil
-        @rdf_type = nil
+        @rdf_type = []
         @rdf_predicates = []
         @rdf_members = []
       end
@@ -24,20 +24,26 @@ module Lutaml
       end
 
       def type(value)
-        @rdf_type = value
+        @rdf_type = Array(value)
       end
 
-      def predicate(name, namespace:, to:, lang_tagged: false)
+      def predicate(name, namespace:, to:, lang_tagged: false,
+                    uri_reference: false)
         @rdf_predicates << Lutaml::Rdf::MappingRule.new(
           name,
           namespace: namespace,
           to: to,
           lang_tagged: lang_tagged,
+          uri_reference: uri_reference,
         )
       end
 
-      def members(attr_name)
-        @rdf_members << Lutaml::Rdf::MemberRule.new(attr_name)
+      def members(attr_name, predicate_name: nil, namespace: nil)
+        @rdf_members << Lutaml::Rdf::MemberRule.new(
+          attr_name,
+          predicate_name: predicate_name,
+          namespace: namespace,
+        )
       end
 
       def mappings(_register_id = nil)
@@ -57,14 +63,14 @@ module Lutaml
       end
 
       def deep_dup
-        self.class.new.tap do |new_mapping|
-          new_mapping.instance_variable_set(:@namespace_set, @namespace_set)
-          new_mapping.instance_variable_set(:@rdf_subject, @rdf_subject)
-          new_mapping.instance_variable_set(:@rdf_type, @rdf_type)
-          new_mapping.instance_variable_set(:@rdf_predicates,
-                                            @rdf_predicates.dup)
-          new_mapping.instance_variable_set(:@rdf_members, @rdf_members.dup)
-        end
+        dup
+      end
+
+      def initialize_copy(source)
+        super
+        @rdf_type = source.rdf_type.dup
+        @rdf_predicates = source.rdf_predicates.dup
+        @rdf_members = source.rdf_members.dup
       end
     end
   end