lutaml-model 0.8.10 → 0.8.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1dea5a70c106b45dafcf2950dda9a8a1c2d8f2d37a4d32ec9a610e461b97a91
-  data.tar.gz: ca6332ea17ae83c4473a5143d454f155006ad369759dab98c48a1ba825aa6d74
+  metadata.gz: 992b8e51bee9c168f1dbb4cac0fcfd75f593f1c40cc29abce7e2163088e6fc48
+  data.tar.gz: 8e3524b5e4336e8cb289c3f31b513727bb2bbb23d3429fcd770425b6f24de489
 SHA512:
-  metadata.gz: 01c6623cc80b904875abe68601be5f4b76f441a0b6d0a599325db9454152072c4548985b29e12656b79cffeb28a965ddbf2d3191c6dc617503d914324cee3d35
-  data.tar.gz: 38c58ea41a62c035f56ba5a6ae758ed45e861417d7b41dba4003418600f36a88b6ab1a6ab753bd3ff54c3c45a2ed25ac13a68c774c9f488e9785d3d5c44894c6
+  metadata.gz: 61c349cf6a1476a0c8668ea19b45e2989275a00d97ab718613eb80cfdc86a2e71ba0cb344c69a6877c5447a57d715f080470c3b28dce0c046652502182b29408
+  data.tar.gz: b85e8858876efa7b98acec6df1ff36e2ebbbf772c8b8cf035a459374159d2c5d704c13cbcecc99a69561438884d05bc4f52d13e12d6cd1b3f63611761344bd04

data/.github/workflows/dependent-repos.json

@@ -29,6 +29,7 @@
     "relaton/loc_mods",
     "relaton/w3c_api",
     "ukiryu/ukiryu",
+    "unitsml/unitsdb-ruby",
     "unitsml/unitsml-ruby"
   ]
 }

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-05-18 04:34:59 UTC using RuboCop version 1.86.0.
+# on 2026-05-20 09:01:31 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -11,13 +11,52 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'lutaml-model.gemspec'
 
-# Offense count: 3012
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/lutaml/turtle/transform.rb'
+    - 'spec/lutaml/model/store_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'spec/lutaml/model/store_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'spec/lutaml/model/store_spec.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
+# SupportedStylesAlignWith: start_of_line, relative_to_receiver
+Layout/IndentationWidth:
+  Exclude:
+    - 'spec/lutaml/model/store_spec.rb'
+
+# Offense count: 3024
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/lutaml/turtle/transform.rb'
+    - 'spec/lutaml/model/store_spec.rb'
+
 # Offense count: 21
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
@@ -130,12 +169,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 310
+# Offense count: 308
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 554
+# Offense count: 553
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
@@ -249,7 +288,7 @@ RSpec/DescribeMethod:
     - 'spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb'
     - 'spec/lutaml/xml/serializable_namespace_spec.rb'
 
-# Offense count: 1257
+# Offense count: 1285
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -324,7 +363,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1490
+# Offense count: 1507
 RSpec/MultipleExpectations:
   Max: 21
 
@@ -398,6 +437,17 @@ Security/MarshalLoad:
   Exclude:
     - 'scripts-xmi-profile/profile_xmi.rb'
 
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/lutaml/model/store_spec.rb'
+
 # Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
 # Configuration parameters: AllowedMethods, AllowedPatterns.

data/README.adoc

@@ -5507,6 +5507,49 @@ vocab.to_turtle
 vocab.to_jsonld
 ----
 
+==== Multiple RDF types
+
+`type` accepts a single compact IRI or an array:
+
+[source,ruby]
+----
+type "skos:Concept"
+# or multiple types:
+type ["skos:Concept", "dcterms:Agent"]
+----
+
+In Turtle, each type produces a separate `a` triple. In JSON-LD, a single type
+produces `"@type": "skos:Concept"` while multiple types produce an array.
+
+==== URI reference predicates
+
+Predicates declared with `uri_reference: true` serialize values as URI objects
+rather than string literals. In Turtle, values are emitted without quotes. In
+JSON-LD, values are wrapped in `{"@id": ...}` and the context term includes
+`"@type": "@id"`.
+
+[source,ruby]
+----
+predicate :related, namespace: SkosNamespace, to: :related, uri_reference: true
+----
+
+Round-trip fidelity is preserved: compact IRI forms (e.g. `"skos:other"`) are
+maintained through serialization and deserialization.
+
+==== Linked member predicates
+
+`members` accepts `predicate_name:` and `namespace:` to generate linking triples
+from the container to each member:
+
+[source,ruby]
+----
+members :children, predicate_name: :member, namespace: SkosNamespace
+----
+
+In Turtle, this produces `skos:member <child-uri>` triples on the container
+subject. In JSON-LD, the context includes a `member` term with `"@type": "@id"`
+and the container resource contains `{"@id": "..."}` references.
+
 See link:docs/_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
 complete guide including language-tagged values, graph serialization, and
 architecture details.

data/docs/_guides/jsonld-serialization.adoc

@@ -160,7 +160,9 @@ end
 ----
 
 See link:../_guides/rdf-serialization.adoc[Unified RDF Serialization] for the
-complete guide including graph-level serialization with `members`.
+complete guide including graph-level serialization with `members`, URI reference
+predicates (`uri_reference: true`), multiple RDF types, and linking predicates
+on member collections.
 
 == Multi-format models
 

data/docs/_guides/rdf-serialization.adoc

@@ -94,15 +94,22 @@ subject { |m| "http://example.org/concept/#{m.code}" }
 
 ==== type
 
-Sets the RDF type (`rdf:type`). Compact IRIs are resolved via declared
-namespaces:
+Sets the RDF type (`rdf:type`). Accepts a single compact IRI or an array of
+compact IRIs. Compact IRIs are resolved via declared namespaces:
 
 [source,ruby]
 ----
 type "skos:Concept"
 # resolves to <http://www.w3.org/2004/02/skos/core#Concept>
+
+# multiple types:
+type ["skos:Concept", "dcterms:Agent"]
 ----
 
+In Turtle, each type produces a separate `a` triple. In JSON-LD, a single type
+produces `"@type": "skos:Concept"` while multiple types produce an array
+`"@type": ["skos:Concept", "dcterms:Agent"]`.
+
 ==== predicate
 
 Each `predicate` creates a mapping between an RDF predicate and a model
@@ -119,13 +126,38 @@ Parameters:
 * `namespace:` — the `Lutaml::Rdf::Namespace` subclass (required)
 * `to:` — the model attribute to read (required)
 * `lang_tagged:` (default: `false`) — if true, values are serialized with
-  language tags (see <<language-tagged-values>>)
+  language tags (see <<language-tagged-values>>). Mutually exclusive with
+  `uri_reference`.
+* `uri_reference:` (default: `false`) — if true, values are serialized as URI
+  references rather than string literals (see <<uri-reference-predicates>>).
+  Mutually exclusive with `lang_tagged`.
 
 ==== members
 
 Declares that a container model contains member resources that should be
 serialized as separate subjects in the output graph (see <<graph-serialization>>).
 
+Optional linking predicate parameters generate relationship triples from the
+container to each member:
+
+[source,ruby]
+----
+members :concepts, predicate_name: :member, namespace: SkosNamespace
+----
+
+When `predicate_name` and `namespace` are provided:
+
+* **Turtle**: produces `skos:member <child-uri>` triples on the container subject
+* **JSON-LD**: adds a `member` term to `@context` with `"@type": "@id"` and
+  `{"@id": "..."}` references in the container resource
+
+Parameters:
+
+* `attr_name` — the model attribute holding the member collection (required)
+* `predicate_name:` — the local name for the linking predicate (optional)
+* `namespace:` — the `Lutaml::Rdf::Namespace` subclass for the linking predicate
+  (required when `predicate_name` is given)
+
 == Serialization
 
 === Turtle
@@ -207,6 +239,48 @@ class LocalizedLiteral < Lutaml::Model::Serializable
 end
 ----
 
+== [[uri-reference-predicates]]URI Reference Predicates
+
+Predicates declared with `uri_reference: true` serialize attribute values as
+URI references rather than string literals:
+
+[source,ruby]
+----
+predicate :related, namespace: SkosNamespace, to: :related, uri_reference: true
+----
+
+**Turtle:**
+
+Values are emitted as URI objects without quotes. Compact IRIs (e.g.
+`"skos:other"`) are resolved to full URIs using the declared namespaces. Full
+URIs (e.g. `"http://example.org/foo"`) are used as-is.
+
+[source,turtle]
+----
+<http://example.org/concept/1> skos:related skos:other .
+----
+
+**JSON-LD:**
+
+Values are wrapped in `{"@id": ...}` objects. The auto-generated `@context`
+includes a term definition with `"@type": "@id"`:
+
+[source,json]
+----
+{
+  "@context": {
+    "related": { "@id": "http://www.w3.org/2004/02/skos/core#related", "@type": "@id" }
+  },
+  "related": [ { "@id": "skos:other" } ]
+}
+----
+
+Round-trip fidelity: compact IRI forms are preserved through serialization and
+deserialization. Values round-trip as `Concept.from_turtle(concept.to_turtle)`
+preserving the original `"skos:other"` compact form.
+
+The `uri_reference` option is mutually exclusive with `lang_tagged`.
+
 == [[graph-serialization]]Graph Serialization
 
 When a container model holds a collection of member resources, use `members` to
@@ -227,11 +301,16 @@ class Vocabulary < Lutaml::Model::Serializable
     type "skos:ConceptScheme"
     predicate :prefLabel, namespace: SkosNamespace, to: :id
 
-    members :concepts
+    members :concepts,
+            predicate_name: :member,
+            namespace: SkosNamespace
   end
 end
 ----
 
+The `predicate_name` and `namespace` parameters on `members` generate linking
+triples from the container to each member.
+
 === Turtle Output with Members
 
 [source,ruby]
@@ -247,7 +326,9 @@ Produces a single Turtle document with the container and all member triples:
 @prefix skos: <http://www.w3.org/2004/02/skos/core#> .
 
 <http://example.org/vocab/iso1087> a skos:ConceptScheme;
-  skos:prefLabel "iso1087" .
+  skos:prefLabel "iso1087";
+  skos:member <http://example.org/concept/2119>;
+  skos:member <http://example.org/concept/2120> .
 
 <http://example.org/concept/2119> a skos:Concept;
   skos:notation "2119";
@@ -272,14 +353,19 @@ Produces a JSON-LD document with `@graph` containing all resources:
 {
   "@context": {
     "skos": "http://www.w3.org/2004/02/skos/core#",
-    "prefLabel": "skos:prefLabel",
-    "notation": "skos:notation"
+    "prefLabel": { "@id": "skos:prefLabel" },
+    "notation": { "@id": "skos:notation" },
+    "member": { "@id": "http://www.w3.org/2004/02/skos/core#member", "@type": "@id" }
   },
   "@graph": [
     {
       "@id": "http://example.org/vocab/iso1087",
       "@type": "skos:ConceptScheme",
-      "prefLabel": "iso1087"
+      "prefLabel": "iso1087",
+      "member": [
+        { "@id": "http://example.org/concept/2119" },
+        { "@id": "http://example.org/concept/2120" }
+      ]
     },
     {
       "@id": "http://example.org/concept/2119",

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/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/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.11"
   end
 end