lutaml-model 0.8.97 → 0.8.99

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dcefe56e003b241812971d37fc9d76d6b6945cb5a138a9fa15f9ce2aa4fbd7d
-  data.tar.gz: 835dfecf768169c9fbc6ab772c2e11dbe593f3f5e9deb7016b09c8088706117c
+  metadata.gz: 41d8d37a85f86f8d8f30d632c36526fe311ba0156f01a096a15717627f29ec72
+  data.tar.gz: f15221cd4017756a1045502f77b588df6ae8f3e62ff39b38ac10c8d6f4a68115
 SHA512:
-  metadata.gz: 7efe4b0bc24f20b9d48e37c33b5e23cf23af7397900a7d788912275a4b396318d916c721b21bc6373de53e99f3f4f0dc29e459c94bba2e2baaf8c4da67232c14
-  data.tar.gz: 59d5412393469b1904c4c6e29bc0ff58b0c6333b5e3710e531d9e7a8ae465e7762993288f04e6147a12a204a8fb581059a24491d9dc90d7f309e78b1bb39b97a
+  metadata.gz: 509fc9f6462f37013113fdcb7a582ca70e9ce0ff021b51c780f9afdd66c03ec2c62213bd0c76a680dc993db138182b7260ed821757b37946b2b61941e2b9b066
+  data.tar.gz: e01bb47f5085c77f6ce840f31ac4f9f243271846267f1083c2c099cfae7f2ced2979f73a61a3a44ea0b0d609b9176a6e8d64e8841994c794382fd0a16c0880f2

data/docs/_guides/gem-integration.adoc

@@ -0,0 +1,85 @@
+---
+title: Integrating lutaml-model in a Gem
+nav_order: 21
+---
+
+= Integrating lutaml-model in a gem
+
+For gem authors, the integration contract is simple: **depend on
+`lutaml-model` and nothing else format-specific.** Every XML, YAML,
+JSON, and TOML engine is resolved at runtime, and the standard
+adapters (Nokogiri through moxml, Psych, the `json` gem, toml-rb
+compatible engines) cover a working default everywhere.
+
+== Declaring the dependency
+
+[source,ruby]
+----
+spec.add_dependency "lutaml-model", "~> 0.8"
+----
+
+Do not add Nokogiri, Ox, Oga, leptris, yeptris, or teptris to your
+gemspec. All engines are optional at runtime:
+
+* when an engine gem is in the end user's bundle, the matching
+  adapters prefer it (see the
+  link:../native-engines[native engines guide]);
+* when it is not, adapters fall back to the standard engine for
+  that format — parsing and generation semantics are identical,
+  error classes are re-raised as their standard-library equivalents.
+
+There is no code path to write, no require order to respect, and no
+capability probe to perform in your gem.
+
+== Testing across adapters
+
+Your test suite should exercise the adapters your users may run.
+Lutaml::Model's own suite parameterizes the XML adapter through an
+environment variable; the same shape works downstream:
+
+[source,ruby]
+----
+ADAPTER = ENV.fetch("XML_ADAPTER", "nokogiri").to_sym
+
+RSpec.configure do |config|
+  config.before(:suite) do
+    Lutaml::Model::Config.xml_adapter_type = ADAPTER
+  end
+end
+----
+
+Run the matrix in CI — one leg per adapter the standard runners can
+install:
+
+[source,sh]
+----
+XML_ADAPTER=nokogiri bundle exec rspec
+XML_ADAPTER=ox bundle exec rspec
+XML_ADAPTER=leptris bundle exec rspec   # requires the leptris gem in that leg's bundle
+----
+
+Engine gems belong in the CI *Gemfile* (a `group :test` entry or a
+separate CI gemfile), never in the gemspec. Start with the primary
+adapter (Nokogiri) and enable further legs incrementally as they
+pass — the same "adapter-first" strategy this library's own suite
+uses.
+
+== Semantics your users can rely on
+
+* Adapter choice never changes results: the plan fast path and the
+  interpretive pipeline produce identical output; on engines below
+  a capability floor the affected models parse interpretively
+  rather than degrade (see the version-floor note in the
+  link:../native-engines[native engines guide]).
+* Parse failures raise the standard error classes wrapped as
+  `Lutaml::Model::InvalidFormatError` on every engine — code that
+  rescues those classes works regardless of the bundle.
+
+== Rules of thumb
+
+* Gemspec: `lutaml-model` only. CI gemfiles: the engines you test.
+* Expose format options you want to forward (pretty printing,
+  encoding) — never the adapter itself.
+* If you ship models for multiple schema versions, see
+  link:../type-registers-contexts[type registers and contexts] for
+  per-version trees and substitution.

data/docs/_guides/index.adoc

@@ -28,8 +28,13 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * link:../advanced-mapping[Advanced Attribute Mapping] - Same-name dispatch on attribute values (`when_attribute`), grouped declarations, custom methods, delegation
 * link:../grammar-backed-formats[Grammar-Backed String Formats] - Register a grammar engine as a serialization format (identifier strings, DSLs)
 
-== Performance
+== Model architecture and integration
+
+* link:../type-registers-contexts[Type Registers and Contexts] - Multi-version class trees, derived contexts, and model substitution
+* link:../gem-integration[Integrating lutaml-model in a Gem] - Dependency contract, adapter deferral, cross-adapter testing
 
+== Performance
+/
 * link:../native-engines[Native engines (leptris / yeptris / teptris)] - Drop-in XML/YAML/JSON/TOML engine upgrades via bundle opt-in
 
 == Linked Data serialization

data/docs/_guides/native-engines.adoc

@@ -67,11 +67,22 @@ When the XML adapter resolves to leptris, XML (de)serialization
 compiles the model's mapping into a leptris descriptor plan and runs
 the whole document through one native pass — measured 6.7x parse and
 4x serialize with -76% / -80% allocations on the plan-path corpus.
-Models the plan cannot express exactly (same-name discriminator
-partitions, namespace-qualified models with deferred-rule shapes) and
-shapes with custom semantics (custom methods, polymorphism, unions,
-ordered children) hydrate through the interpretive pipeline or a
-per-subtree fragment of it, unchanged.
+Namespace-qualified models ride the path too: serialization spells
+prefixed element and attribute names through the same namespace
+planning the interpretive writer uses, and every `(prefix, uri)`
+pair is declared once on the output root. Models the plan cannot
+express exactly (same-name discriminator partitions, deferred-rule
+shapes) and shapes with custom semantics (custom methods,
+polymorphism, unions, ordered children) hydrate through the
+interpretive pipeline or a per-subtree fragment of it, unchanged.
+
+Version floor note: leptris 1.9.320+ retains child-row namespace
+URIs engine-side and matches plain attribute rows against
+namespace-qualified wire spellings. On older engines, models whose
+plans carry exact-URI child rows or plain attribute rows under a
+namespaced chain parse interpretively for correctness — a per-model
+fallback, not an error. Bundles resolving leptris 1.9.320+ get the
+full fast path.
 
 The path is on by default and is a no-op without leptris (standard
 adapters keep the classic pipeline). Opt out for the whole process:

data/docs/_guides/type-registers-contexts.adoc

@@ -0,0 +1,126 @@
+---
+title: Type Registers and Contexts
+nav_order: 20
+---
+
+= Type registers and contexts
+
+Lutaml::Model resolves every attribute type — Symbol or class —
+through a per-application *register*: a named table of types scoped
+so that different class trees can share mapping definitions without
+colliding. Registers are the mechanism behind multi-version model
+suites and model substitution.
+
+== Registers
+
+A register maps type ids to classes. Classes declare the register
+they belong to:
+
+[source,ruby]
+----
+module MyModels
+  class Mi < Lutaml::Model::Serializable
+    def self.lutaml_default_register
+      :my_models
+    end
+  end
+end
+----
+
+Symbol attribute types resolve in the declaring class's register,
+so the same symbol can mean different classes per tree — the
+multi-version pattern below builds on this.
+
+== Contexts: derived registers with substitutions
+
+A *context* is a derived type-resolution scope: it carries a
+registry, fallback registers, and — the part that powers model
+substitution — a list of type substitutions. Contexts are created
+through the global registry:
+
+[source,ruby]
+----
+Lutaml::Model::GlobalContext.create_context(
+  id: :custom_models,
+  fallback_to: [:my_models],
+  substitutions: [
+    { from_type: MyModels::Mover, to_type: Overset },
+  ],
+)
+
+instance = MyModels::Math.from_xml(xml, context: :custom_models)
+instance.mover_value.first # => #<Overset>
+----
+
+Every attribute whose type resolves to `MyModels::Mover` — at any
+depth of the tree — hydrates `Overset` in that context. Substitution
+is type-based, so "swap this class everywhere it is referenced" and
+"swap it only inside this one path" are the same operation scoped by
+context: create two contexts with different substitution lists.
+
+Contexts are cheap and disposable:
+
+[source,ruby]
+----
+Lutaml::Model::GlobalContext.unregister_context(:custom_models)
+----
+
+=== The custom-models convenience
+
+A whole-table convenience reads exactly like a class-swap hash and
+derives the context for you:
+
+[source,ruby]
+----
+models = { MyModels::Mover => Overset, MyModels::Mi => BoldMi }
+Lutaml::Model::GlobalContext.create_context(
+  id: :custom, fallback_to: [:my_models],
+  substitutions: models.map { |from, to| { from_type: from, to_type: to } },
+)
+MyModels::Math.from_xml(xml, context: :custom)
+----
+
+Substitute classes should inherit from the class they replace (or
+provide its full attribute surface) so mappings and serialization
+keep working.
+
+=== Substituting a symbol entry instead of a class
+
+Registers accept direct class registrations under a type id — useful
+when a tree declares `attribute :row, :row` and you want the symbol
+to resolve to your own class within a derived register:
+
+[source,ruby]
+----
+derived = Lutaml::Model::Register.new(:derived, fallback: [:my_models])
+derived.register_model(NewRow, id: :row)
+MyModels::Doc.from_xml(xml, register: derived)
+----
+
+(`register:` is the pre-context spelling; prefer `context:` with
+substitutions in new code.)
+
+== Multi-version class trees
+
+The flagship pattern combines registers with per-version classes
+and shared mapping modules:
+
+* a `Base::Mrow` module holds the mapping DSL once;
+* each version declares `class Mrow` mixing the module in and
+  pointing `lutaml_default_register` at its version's register;
+* attributes use symbol types, so `attribute :mrow, :mrow` means
+  the right class per tree;
+* a substitution context swaps individual classes for one call
+  without re-opening or redefining anything.
+
+Nothing re-opens generated classes, and each version's tree stays
+independent — no hidden delegation.
+
+== Rules of thumb
+
+* Prefer contexts over global configuration: substitutions scoped
+  to a context cannot leak into other resolutions.
+* Substitute classes should inherit the original; substitution then
+  preserves every mapping declared on the base.
+* Clean up exploratory contexts with `unregister_context` in test
+  teardowns — contexts are global state.

data/lib/lutaml/model/attribute.rb

@@ -1240,7 +1240,16 @@ instance_object = nil)
         # instead of three per serialized scalar. Reference and
         # custom-serializer rows keep the wrapped path.
         if resolved_type <= Type::Reference ||
-            Type::Value.format_type_serializer_for(format, resolved_type)&.dig(:to)
+            (registered_to = Type::Value.format_type_serializer_for(format, resolved_type)&.dig(:to))
+          # String→String under the default :xml serializer is the
+          # identity — the wrapper mint per string value on the XML
+          # serialize path is pure waste. A consumer override of the
+          # serializer disables the fast path via the proc comparison.
+          if resolved_type == Type::String && value.is_a?(::String) &&
+              registered_to == Lutaml::Xml::Type::Serializers::STRING_XML_TO
+            return value
+          end
+
           value = wrap_in_type_if_needed(value, resolved_type)
           return value.public_send(TO_FORMAT_METHODS[format] || :"to_#{format}")
         end

data/lib/lutaml/model/schema/base_schema.rb

@@ -16,6 +16,21 @@ module Lutaml
 
             format_schema(schema, options)
           end
+
+          # Generate one schema document covering several model classes.
+          # The roots share a single $defs map and no top-level $ref is
+          # emitted; each root stays addressable under $defs by its class
+          # name. Use generate for a single root with a top-level $ref.
+          def generate_many(klasses, options = {})
+            schema = {
+              "$schema" => options[:schema],
+              "$id" => options[:id],
+              "description" => options[:description],
+              "$defs" => Generator::DefinitionsCollection.from_classes(klasses).to_schema,
+            }.compact
+
+            format_schema(schema, options)
+          end
         end
 
         attr_reader :schema, :klass

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

@@ -14,6 +14,16 @@ module Lutaml
               collection
             end
 
+            # Build one collection covering several roots. The seen-set
+            # is shared across roots so a class referenced by more than
+            # one of them registers once.
+            def from_classes(klasses)
+              collection = new
+              seen = {}
+              klasses.each { |klass| register_definition(collection, klass, seen) }
+              collection
+            end
+
             def process_attributes(collection, klass, seen = {})
               register = extract_register_from(klass)
               klass.attributes.each_value do |attribute|

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

@@ -13,6 +13,12 @@ module Lutaml
           case value
           when ::Time then value
           when ::DateTime then value.to_time
+          when ::Integer
+            # YAML 1.1 sexagesimal: psych resolves an unquoted hh:mm:ss
+            # scalar to seconds since midnight (25200 for "07:00:00").
+            # Feeding that integer through Time.parse yields a garbage
+            # date — reconstruct the wall-clock time of the current day.
+            ::Date.today.to_time + value
           else ::Time.parse(value.to_s)
           end
         rescue ArgumentError

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.97"
+    VERSION = "0.8.99"
   end
 end

data/lib/lutaml/xml/leptris/plan_compiler.rb

@@ -48,6 +48,12 @@ module Lutaml
           end
         end.cache
 
+        # Name-matched element row kinds eligible for the :unqualified
+        # ns form (leptris#1560). Text rows (content) match no element
+        # name and wildcard rows carry their own :any.
+        ROW_KINDS_NS_UNQUALIFIED = %i[scalar collection nested callback
+                                      raw].freeze
+
         class << self
           def compile(model_class, register)
             # Version gate, not a capability probe: the plan path needs
@@ -74,9 +80,13 @@ module Lutaml
             # is THREAD-LOCAL (a shared in-progress set races: a concurrent
             # same-key compile would cache false permanently — the #828
             # lesson); the nil at the cycle point is NOT cached — the
-            # outermost build completes and caches the real verdict.
+            # outermost build completes and caches the real verdict. The
+            # :cycle stat makes the guard visible in plan_stats — without
+            # it a cyclic graph (uniword pict↔shape, sdt→sdt) reads as
+            # "nil with an empty histogram", indistinguishable from a
+            # silent build failure.
             stack = (Thread.current[:plan_compiler_stack] ||= [])
-            return nil if stack.include?(key)
+            return opt_out!(:cycle) if stack.include?(key)
 
             stack.push(key)
             begin
@@ -323,6 +333,22 @@ module Lutaml
             # inherit the default xmlns, so the strict no-URI default
             # dropped every child of a namespaced document.
             flags << :ns_lenient
+
+            # Namespace-less model child rows bind the strict unwritten
+            # spelling (bare, or inherited default xmlns) on engines
+            # with the leptris#1560 :unqualified form — the interpretive
+            # matcher's exact no-namespace semantic, refusing prefixed
+            # spellings where the ns_lenient superset bound them.
+            # Rows with an explicit form (rule ns, type ns, :none, :any)
+            # are untouched; name-matched element row kinds only.
+            if model_ns.nil? && Leptris.ns_unqualified_rows_compatible?
+              rows.each do |r|
+                next if r[:ns]
+
+                r[:ns] = :unqualified if ROW_KINDS_NS_UNQUALIFIED.include?(r[:kind])
+              end
+            end
+
             tree = { name: mapping.root_element.to_s,
                      attributes: plan_attrs, children: rows }
             tree[:ns] = model_ns if model_ns

data/lib/lutaml/xml/leptris/plan_serializer.rb

@@ -186,6 +186,8 @@ module Lutaml
                     inherited_ns = nil)
             reg ||= register
             write_attributes(element, instance, plan, reg, ns_ctx)
+            ns_index = ns_index_for(plan)
+            nested_plans = nested_plans_for(plan)
             plan[:rows].each do |rule, attr, kind, spelling, delegate|
               value = value_of(instance, attr, delegate)
               next unless rule.render?(value, instance)
@@ -196,9 +198,7 @@ module Lutaml
                 # several occurrences serializes one element per item,
                 # as the interpretive writer does. A plain scalar skips
                 # the Array() wrap — the common case.
-                row_ns = plan[:tree][:children]&.find do |r|
-                  r[:name] == rule.name.to_s
-                end&.[](:ns) || inherited_ns
+                row_ns = ns_index[row_name(rule, spelling)] || inherited_ns
                 if value.is_a?(::Array)
                   value.each do |item|
                     add_leaf(element,
@@ -213,9 +213,7 @@ module Lutaml
                            attrs: rule.when_attribute)
                 end
               when :collection_native, :collection_cb
-                row_ns = plan[:tree][:children]&.find do |r|
-                  r[:name] == rule.name.to_s
-                end&.[](:ns) || inherited_ns
+                row_ns = ns_index[rule.name.to_s] || inherited_ns
                 Array(value).each do |item|
                   add_leaf(element,
                            ns_ctx ? ns_ctx.spell(rule.name.to_s, row_ns) : rule.name.to_s,
@@ -224,7 +222,8 @@ module Lutaml
                 end
               when :nested, :ordered_deferred
                 Array(value).each do |item|
-                  child_plan = PlanCompiler.compile(item.class, reg)
+                  child_plan = nested_plans[item.class] ||
+                    (nested_plans[item.class] = PlanCompiler.compile(item.class, reg))
                   child_ns = child_plan[:tree][:ns] || inherited_ns
                   child = element.create_child(
                     ns_ctx ? ns_ctx.spell(child_plan[:tree][:name], child_ns) : child_plan[:tree][:name],
@@ -246,6 +245,25 @@ module Lutaml
             end
           end
 
+          # Per-plan lazy indexes: the name→ns lookup and the
+          # per-class child-plan resolution are per-instance calls on
+          # the serialize hot path — memoized once per compiled plan
+          # they cost nothing per row (the old per-row children#find
+          # plus PlanCompiler key arrays were ~4 allocs/row).
+          def ns_index_for(plan)
+            plan[:ns_index] ||= begin
+              h = {}
+              (plan[:tree][:children] || []).each do |r|
+                h[r[:name]] = r[:ns] unless h.key?(r[:name])
+              end
+              h
+            end
+          end
+
+          def nested_plans_for(plan)
+            plan[:nested_plans] ||= {}
+          end
+
           # Element_order-driven emission (the interpretive order
           # applier's contract): text runs and comments verbatim, each
           # element entry consuming the next item of its collection
@@ -327,7 +345,8 @@ module Lutaml
                          end
                   next unless item
 
-                  child_plan = PlanCompiler.compile(item.class, reg)
+                  child_plan = nested_plans_for(plan)[item.class] ||
+                    (nested_plans_for(plan)[item.class] = PlanCompiler.compile(item.class, reg))
                   child = element.create_child(child_plan[:tree][:name])
                   if child_plan[:ordered]
                     return nil unless build_ordered(child, item, child_plan,
@@ -351,8 +370,9 @@ module Lutaml
           def write_attributes(element, instance, plan, reg = nil,
                                ns_ctx = nil)
             recorded = instance.attribute_order
-            attr_prefixes = {}
-            if ns_ctx
+            attr_prefixes = nil
+            if ns_ctx && !(plan[:tree][:attributes] || []).empty?
+              attr_prefixes = {}
               (plan[:tree][:attributes] || []).each do |a|
                 form = a[:ns].is_a?(Hash) ? a[:ns] : nil
                 # Namespaced attributes always spell prefixed (W3C:
@@ -376,13 +396,13 @@ module Lutaml
                 plan[:attr_rows].map { |rule, _a, _s, _d| rule.name.to_s }
               names.each do |name|
                 write_attribute(element, instance, name, by_name[name],
-                                reg, attr_prefixes[name])
+                                reg, attr_prefixes && attr_prefixes[name])
               end
             else
               plan[:attr_rows].each do |rule, attr, _sp, delegate|
                 write_attribute(element, instance, rule.name.to_s,
                                 [rule, attr, delegate], reg,
-                                attr_prefixes[rule.name.to_s])
+                                attr_prefixes && attr_prefixes[rule.name.to_s])
               end
             end
           end

data/lib/lutaml/xml/leptris.rb

@@ -42,6 +42,14 @@ module Lutaml
       # through PlanCompiler.engine_walk_safe?.
       MIN_LEPTRIS_WALK_NS_SAFETY_VERSION = "1.9.320.0"
 
+      # The :unqualified child-row ns form (leptris#1560: matches only
+      # the UNWRITTEN spelling — bare or inherited-default-ns — and
+      # refuses prefixed spellings, the interpretive matcher's exact
+      # no-namespace semantic) ships in binding 1.9.323.0. Older
+      # engines keep namespace-less model rows on the ns_lenient
+      # superset (local-name matching under any qualification).
+      MIN_LEPTRIS_NS_UNQUALIFIED_VERSION = "1.9.323.0"
+
       def self.plan_path_compatible?
         return false unless defined?(Gem)
 
@@ -82,6 +90,13 @@ module Lutaml
           !!(spec && spec.version >= Gem::Version.new(MIN_LEPTRIS_WALK_NS_SAFETY_VERSION))
       end
 
+      def self.ns_unqualified_rows_compatible?
+        return false unless defined?(Gem)
+
+        spec = Gem.loaded_specs["leptris"]
+        spec && spec.version >= Gem::Version.new(MIN_LEPTRIS_NS_UNQUALIFIED_VERSION)
+      end
+
       autoload :PlanCompiler, "lutaml/xml/leptris/plan_compiler"
       autoload :PlanHydrator, "lutaml/xml/leptris/plan_hydrator"
       autoload :PlanOrder, "lutaml/xml/leptris/plan_order"

data/lib/lutaml/xml/namespace_collector.rb

@@ -409,9 +409,25 @@ module Lutaml
             # Handle collections and arrays
             if child_instance.is_a?(Array) || child_instance.is_a?(Lutaml::Model::Collection)
               instances = child_instance.is_a?(Lutaml::Model::Collection) ? child_instance.collection : child_instance
-              # Collect needs from all instances and merge
+              # Collect needs from the FIRST instance of each distinct
+              # class and merge once — instances of one class share the
+              # mapping graph, so re-collecting every member re-walks
+              # identical structure (row-heavy models spent most of
+              # their serialize budget here). Value-dependent divergences
+              # in later members surface as unspellable forms on the
+              # serializer and fall back interpretively, never as wrong
+              # output. Merge-once is equivalent to merge-N: every read
+              # path of the merged needs is any?/set-based.
               merged_needs = NamespaceNeeds.new
+              seen_classes = nil
               instances.each do |item|
+                item_class = item.class
+                if seen_classes
+                  next if seen_classes[item_class]
+                else
+                  seen_classes = {}
+                end
+                seen_classes[item_class] = true
                 item_ns_prefix = if item.is_a?(::Lutaml::Model::Serialize)
                                    item.xml_namespace_prefix
                                  end

data/lib/lutaml/xml/type/serializers.rb

@@ -8,13 +8,20 @@ module Lutaml
       module Serializers
         module_function
 
+        # The default :xml String serializer is the identity for String
+        # values. Attribute#serialize_value fast-paths String→String
+        # through an identity comparison with this exact proc, so a
+        # consumer override of the serializer disables that fast path
+        # automatically.
+        STRING_XML_TO = ->(inst) { inst.value&.to_s }.freeze
+
         def register_all!
           v = Lutaml::Model::Type::Value
 
           # String — value&.to_s
           v.register_format_type_serializer(
             :xml, Lutaml::Model::Type::String,
-            to: ->(inst) { inst.value&.to_s },
+            to: STRING_XML_TO,
             from: ->(val) { Lutaml::Model::Type::String.cast(val) }
           )
 

data/spec/lutaml/model/schema/generate_many_spec.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+module GenerateManySpec
+  class Source < Lutaml::Model::Serializable
+    attribute :name, :string
+  end
+
+  class Other < Lutaml::Model::Serializable
+    attribute :label, :string
+  end
+
+  class Consumer < Lutaml::Model::Serializable
+    attribute :inner, Source
+  end
+end
+
+RSpec.describe Lutaml::Model::Schema::BaseSchema do
+  describe ".generate_many" do
+    it "covers every root in one document without a top-level $ref" do
+      parsed = JSON.parse(
+        Lutaml::Model::Schema::JsonSchema.generate_many(
+          [GenerateManySpec::Source, GenerateManySpec::Other],
+        ),
+      )
+
+      expect(parsed).not_to have_key("$ref")
+      expect(parsed["$defs"]).to have_key("GenerateManySpec_Source")
+      expect(parsed["$defs"]).to have_key("GenerateManySpec_Other")
+    end
+
+    it "registers a class shared by several roots once" do
+      parsed = JSON.parse(
+        Lutaml::Model::Schema::JsonSchema.generate_many(
+          [GenerateManySpec::Source, GenerateManySpec::Consumer],
+        ),
+      )
+
+      expect(parsed["$defs"].keys.size).to eq(2)
+      expect(parsed["$defs"]).to have_key("GenerateManySpec_Consumer")
+    end
+
+    it "formats YAML output" do
+      yaml = Lutaml::Model::Schema::YamlSchema.generate_many(
+        [GenerateManySpec::Source, GenerateManySpec::Other],
+      )
+
+      expect(yaml).to start_with("%YAML")
+    end
+  end
+
+  describe "Generator::DefinitionsCollection.from_classes" do
+    it "builds one collection covering all roots" do
+      collection = Lutaml::Model::Schema::Generator::DefinitionsCollection
+        .from_classes([GenerateManySpec::Source, GenerateManySpec::Consumer])
+
+      expect(collection.to_schema.keys.size).to eq(2)
+    end
+  end
+end

data/spec/person_spec.rb

@@ -115,13 +115,14 @@ RSpec.describe Person do
     expect(model.to_yaml).to eq(attributes_yaml.to_yaml)
   end
 
-  # yeptris 0.6.29.x regressed the time-only scalar anchor: "07:00:00"
-  # comes back as a fixed 2025-07-19 00:00 instead of today-07:00
-  # (psych answers exactly; verified on the psych path). Re-pended
-  # until the yeptris typed-materialize ships the fix — evidence on
-  # moxml#336. 873a67bd un-pended these on the premise that the
-  # 0.6.28.x behavior held; it did not survive the 0.6.29 cut.
-  xit "deserializes from YAML" do # rubocop:disable RSpec/PendingWithoutReason -- yeptris time-only misparse; engine fix pending.
+  # Root cause of the long-pended time-only misparse: psych resolves an
+  # unquoted hh:mm:ss scalar as a YAML 1.1 sexagesimal integer (25200
+  # for "07:00:00"), and the :time cast fed that integer through
+  # Time.parse, which reads "25200" as a date (the fixed 2025-07-19
+  # garbage). The cast now reads sexagesimal integers as seconds since
+  # midnight — both the psych and yeptris paths answer today-07:00.
+  # Evidence chain: moxml#336, yeptris-ruby#265.
+  it "deserializes from YAML" do
     yaml = attributes_yaml.to_yaml
     person = described_class.from_yaml(yaml)
     expect(person.first_name).to eq("John")
@@ -133,8 +134,8 @@ RSpec.describe Person do
     expect(person.active).to be true
   end
 
-  # Same yeptris time-only scalar misparse as above.
-  xit "deserializes from YAML array" do # rubocop:disable RSpec/PendingWithoutReason -- yeptris time-only misparse; engine fix pending.
+  # Same sexagesimal time-only scalar as above.
+  it "deserializes from YAML array" do
     yaml = [attributes_yaml.dup, attributes_yaml.dup].to_yaml
 
     persons = described_class.from_yaml(yaml)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.97
+  version: 0.8.99
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -207,6 +207,7 @@ files:
 - docs/_guides/creating-xsd.adoc
 - docs/_guides/custom-methods.adoc
 - docs/_guides/document-validation.adoc
+- docs/_guides/gem-integration.adoc
 - docs/_guides/grammar-backed-formats.adoc
 - docs/_guides/index.adoc
 - docs/_guides/jsonld-serialization.adoc
@@ -220,6 +221,7 @@ files:
 - docs/_guides/schema-generation.adoc
 - docs/_guides/schema-import.adoc
 - docs/_guides/turtle-serialization.adoc
+- docs/_guides/type-registers-contexts.adoc
 - docs/_guides/value-transformations.adoc
 - docs/_guides/xml-mapping.adoc
 - docs/_guides/xml-mappings-guide.adoc
@@ -1796,6 +1798,7 @@ files:
 - spec/lutaml/model/root_mappings_spec.rb
 - spec/lutaml/model/rule_value_extractor_spec.rb
 - spec/lutaml/model/runtime_compatibility_spec.rb
+- spec/lutaml/model/schema/generate_many_spec.rb
 - spec/lutaml/model/schema/generation_regressions_spec.rb
 - spec/lutaml/model/schema/generator/definitions_collection_spec.rb
 - spec/lutaml/model/schema/json_schema_spec.rb