lutaml-model 0.8.18 → 0.8.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 852a93ce391ef7eb0f8e7673bda66f7bb417637b252735cebe833d1e305a6c7b
-  data.tar.gz: 65f067c3e0bf4e1d520d5e2d133a6de4606900844b5e91d367ce4edee51da0e1
+  metadata.gz: a30fcd552dca587769736a81de33b66909c592cbc5ed40f696d34fbaf7de887f
+  data.tar.gz: b15506fd1398cad525dcac0a624166cdc23dedf7faa3e282b1aae10c583b405a
 SHA512:
-  metadata.gz: 318f15b16d919319fd4c2cd9c2722a1ee37b8f1a4272b5a966ce45bf2811447c7c1004642fd76c3204ddd70c8fb4ac6de9397e67f7305529e4b2310769fca52b
-  data.tar.gz: 65479ec0a4e9ef58938953f94802da282bfe2d443c4d7cd41a9bf83973e653c3d6ce700fb9eb07e7e5cf1ffa120cfb54fded8d71d8215f4e35c76360dd6393fe
+  metadata.gz: 061ea9253cc7e425f9591e5f57407935eb6b52b1ee69fc5b289b672a0109f8aa3850097d0dd3971613b6010c5e8d83b5425e3447bebe0ae6724916fbdc7a3173
+  data.tar.gz: 9280bc8adfdeaa2e6167c57379d0d40a7c8c27a4dffb420c8f8b6468b893df8ae72207d5fddef2885d4954ba4c45918a1f9cd3746ef2194aed3b09bae46b19f9

data/.github/workflows/dependent-tests.yml

@@ -22,7 +22,7 @@ jobs:
     uses: metanorma/ci/.github/workflows/dependent-rake.yml@main
     with:
       command: bundle exec rspec
-      setup-tools: 'inkscape,ghostscript,exiftool,ffmpeg,imagemagick'
+      setup-tools: 'inkscape,ghostscript,exiftool,ffmpeg,imagemagick,yq'
       after-setup-ruby: |
         if [ -f frontend/package.json ]; then cd frontend && npm install && npm run build; fi
     secrets:

data/.github/workflows/rake.yml

@@ -25,6 +25,7 @@ jobs:
         experimental: [false]
         include:
           - os: windows-latest
+            ruby: head
             experimental: true
     steps:
       - uses: actions/checkout@v6

data/.rubocop.yml

@@ -8,7 +8,7 @@ plugins:
 - rubocop-rspec
 
 AllCops:
-  TargetRubyVersion: 3.2
+  TargetRubyVersion: 3.0
   NewCops: enable
   Exclude:
     - 'vendor/**/*'

data/.rubocop_todo.yml

@@ -1,75 +1,134 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-06-08 11:45:37 UTC using RuboCop version 1.87.0.
+# on 2026-08-25 07:32:39 UTC using RuboCop version 1.90.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
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 1
-Gemspec/RequiredRubyVersion:
-  Exclude:
-    - 'lutaml-model.gemspec'
-
-# Offense count: 1
+# Offense count: 88
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
+  Enabled: false
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_element, with_fixed_indentation
+Layout/ArrayAlignment:
   Exclude:
-    - 'lib/lutaml/rdf/linked_data_transform.rb'
+    - 'spec/lutaml/model/serialize/builder_spec.rb'
+    - 'spec/lutaml/model/union_attribute_spec.rb'
 
-# Offense count: 2
+# Offense count: 7
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: IndentationWidth.
+Layout/AssignmentIndentation:
+  Exclude:
+    - 'lib/lutaml/model/schema/xml_compiler/element_order.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+
+# Offense count: 25
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
+    - 'lib/compat/opal/generate_boot.rb'
+    - 'lib/lutaml/model/schema/file_writer.rb'
+    - 'lib/lutaml/model/schema/renderers/mappings.rb'
+    - 'lib/lutaml/model/schema/renderers/member_decls.rb'
+    - 'lib/lutaml/model/schema/rnc_compiler.rb'
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+    - 'lib/lutaml/model/union.rb'
+    - 'spec/lutaml/model/attribute_spec.rb'
+    - 'spec/lutaml/xml/schema/rnc_compiler_spec.rb'
+    - 'spec/lutaml/xml/schema/rng_compiler_spec.rb'
 
-# Offense count: 2
+# Offense count: 25
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
+    - 'lib/compat/opal/generate_boot.rb'
+    - 'lib/lutaml/model/schema/file_writer.rb'
+    - 'lib/lutaml/model/schema/renderers/mappings.rb'
+    - 'lib/lutaml/model/schema/renderers/member_decls.rb'
+    - 'lib/lutaml/model/schema/rnc_compiler.rb'
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+    - 'lib/lutaml/model/union.rb'
+    - 'spec/lutaml/model/attribute_spec.rb'
+    - 'spec/lutaml/xml/schema/rnc_compiler_spec.rb'
+    - 'spec/lutaml/xml/schema/rng_compiler_spec.rb'
 
-# Offense count: 2
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: special_inside_parentheses, consistent, align_brackets
-Layout/FirstArrayElementIndentation:
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
   Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
+    - 'lib/lutaml/model/schema/renderers/model.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
 
-# Offense count: 4
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler.rb'
+
+# Offense count: 33
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'lib/lutaml/model/schema/rnc_compiler/source_resolver.rb'
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/rng_compiler/element_visitor.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/complex_types.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+    - 'spec/lutaml/model/union_attribute_spec.rb'
+
+# Offense count: 50
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
 # SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
-
-# Offense count: 3071
+    - 'lib/compat/opal/generate_boot.rb'
+    - 'lib/lutaml/model/schema/file_writer.rb'
+    - 'lib/lutaml/model/schema/renderers/mappings.rb'
+    - 'lib/lutaml/model/schema/renderers/member_decls.rb'
+    - 'lib/lutaml/model/schema/rnc_compiler.rb'
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+    - 'lib/lutaml/model/union.rb'
+    - 'spec/lutaml/model/attribute_spec.rb'
+    - 'spec/lutaml/xml/schema/rnc_compiler_spec.rb'
+    - 'spec/lutaml/xml/schema/rng_compiler_spec.rb'
+
+# Offense count: 3250
 # 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: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: symmetrical, new_line, same_line
-Layout/MultilineArrayBraceLayout:
-  Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
-
-# Offense count: 1
+# Offense count: 89
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
-  Exclude:
-    - 'lib/lutaml/rdf/linked_data_transform.rb'
+  Enabled: false
 
 # Offense count: 21
 # Configuration parameters: AllowedMethods.
@@ -82,12 +141,14 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/lutaml/xml/type_namespace_prefix_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 35
+# Offense count: 37
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
 
 # Offense count: 3
+# Configuration parameters: DelegatingMethods, AllowedCrossFilePaths.
+# DelegatingMethods: delegate
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/xml/mapping.rb'
@@ -133,11 +194,6 @@ Lint/ReturnInVoidContext:
   Exclude:
     - 'lib/lutaml/model/serialize/builder.rb'
 
-# Offense count: 1
-Lint/ShadowedException:
-  Exclude:
-    - 'lib/lutaml/model/schema/xml_compiler/xml_namespace_class.rb'
-
 # Offense count: 1
 Lint/StructNewOverride:
   Exclude:
@@ -161,12 +217,12 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/lutaml/xml/mapping_rule.rb'
 
-# Offense count: 346
+# Offense count: 357
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 40
+# Offense count: 42
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -177,23 +233,23 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 6
 
-# Offense count: 307
+# Offense count: 319
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 554
+# Offense count: 584
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 514
 
-# Offense count: 81
+# Offense count: 89
 # Configuration parameters: CountKeywordArgs.
 Metrics/ParameterLists:
   MaxOptionalParameters: 5
   Max: 25
 
-# Offense count: 261
+# Offense count: 268
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -215,7 +271,7 @@ Naming/MethodParameterName:
     - 'lib/lutaml/model/type_context.rb'
     - 'lib/lutaml/xml/namespace.rb'
 
-# Offense count: 11
+# Offense count: 10
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
 # AllowedMethods: call
 # WaywardPredicates: infinite?, nonzero?
@@ -223,7 +279,6 @@ Naming/PredicateMethod:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
     - 'lib/lutaml/model/mapping/mapping_rule.rb'
-    - 'lib/lutaml/model/schema/xml_compiler/complex_type.rb'
     - 'lib/lutaml/xml/model_transform.rb'
     - 'lib/lutaml/xml/namespace_needs.rb'
     - 'lib/lutaml/xml/namespace_resolution_strategy.rb'
@@ -279,13 +334,13 @@ RSpec/BeforeAfterAll:
     - 'spec/lutaml/xml/fpi_namespace_spec.rb'
     - 'spec/lutaml/xml/namespace_spec.rb'
 
-# Offense count: 100
+# Offense count: 113
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 102
+# Offense count: 107
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -296,7 +351,7 @@ RSpec/DescribeMethod:
     - 'spec/lutaml/xml/schema/xsd/schema_helper_methods_spec.rb'
     - 'spec/lutaml/xml/serializable_namespace_spec.rb'
 
-# Offense count: 1343
+# Offense count: 1428
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 68
@@ -361,9 +416,10 @@ RSpec/MessageSpies:
   Exclude:
     - 'spec/lutaml/key_value/transformation/rule_compiler_spec.rb'
 
-# Offense count: 6
+# Offense count: 7
 RSpec/MultipleDescribes:
   Exclude:
+    - 'spec/lutaml/model/defaults_spec.rb'
     - 'spec/lutaml/model/namespace_versioning_spec.rb'
     - 'spec/lutaml/model/transformation_builder_spec.rb'
     - 'spec/lutaml/xml/compiled_rule_namespace_spec.rb'
@@ -371,11 +427,11 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/xml/namespace_resolution_strategy_spec.rb'
     - 'spec/lutaml/xml/xml_space_type_spec.rb'
 
-# Offense count: 1576
+# Offense count: 1668
 RSpec/MultipleExpectations:
   Max: 21
 
-# Offense count: 190
+# Offense count: 198
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 15
@@ -419,7 +475,7 @@ RSpec/RepeatedExampleGroupDescription:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
 
-# Offense count: 39
+# Offense count: 31
 # Configuration parameters: CustomTransform, IgnoreMethods, IgnoreMetadata, InflectorPath, EnforcedInflector.
 # SupportedInflectors: default, active_support
 RSpec/SpecFilePathFormat:
@@ -445,7 +501,7 @@ Security/MarshalLoad:
   Exclude:
     - 'scripts-xmi-profile/profile_xmi.rb'
 
-# Offense count: 3
+# Offense count: 38
 # 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
@@ -454,7 +510,18 @@ Security/MarshalLoad:
 # AllowedMethods: lambda, proc, it
 Style/BlockDelimiters:
   Exclude:
-    - 'spec/lutaml/model/choice_restrict_spec.rb'
+    - 'lib/compat/opal/generate_boot.rb'
+    - 'lib/lutaml/model/schema/file_writer.rb'
+    - 'lib/lutaml/model/schema/renderers/mappings.rb'
+    - 'lib/lutaml/model/schema/renderers/member_decls.rb'
+    - 'lib/lutaml/model/schema/rnc_compiler.rb'
+    - 'lib/lutaml/model/schema/rng_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+    - 'lib/lutaml/model/union.rb'
+    - 'spec/lutaml/model/attribute_spec.rb'
+    - 'spec/lutaml/xml/schema/rnc_compiler_spec.rb'
+    - 'spec/lutaml/xml/schema/rng_compiler_spec.rb'
 
 # Offense count: 2
 # This cop supports unsafe autocorrection (--autocorrect-all).
@@ -501,6 +568,17 @@ Style/MixinUsage:
     - 'bench/bench_unitsml.rb'
     - 'bench/bench_xmi.rb'
 
+# Offense count: 19
+# This cop supports safe autocorrection (--autocorrect).
+Style/MultilineIfModifier:
+  Exclude:
+    - 'lib/lutaml/model/attribute.rb'
+    - 'lib/lutaml/model/schema/rnc_compiler/source_resolver.rb'
+    - 'lib/lutaml/model/schema/rng_compiler/element_visitor.rb'
+    - 'lib/lutaml/model/schema/xml_compiler.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder.rb'
+    - 'lib/lutaml/model/schema/xml_compiler/spec_builder/members.rb'
+
 # Offense count: 12
 # Configuration parameters: AllowedClasses.
 Style/OneClassPerFile:
@@ -539,20 +617,3 @@ Style/SafeNavigation:
 Style/SafeNavigationChainLength:
   Exclude:
     - 'lib/lutaml/xml/mapping.rb'
-
-# Offense count: 3
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: Mode.
-Style/StringConcatenation:
-  Exclude:
-    - 'lib/lutaml/model/schema/xml_compiler/complex_type.rb'
-    - 'lib/lutaml/model/schema/xml_compiler/simple_type.rb'
-    - 'lib/lutaml/model/schema/xml_compiler/xml_namespace_class.rb'
-
-# Offense count: 1
-# child_names_set may be a Set; Array#intersect? requires an Array, so
-# the autocorrect from rubocop 1.88.2's Style/ArrayIntersect would
-# break runtime. Use the block form.
-Style/ArrayIntersect:
-  Exclude:
-    - 'lib/lutaml/xml/model_transform.rb'

data/bench/bench_common.rb

@@ -22,23 +22,26 @@ module BenchCommon
   module_function
 
   # Measure parse time and allocations for a block
-  def measure(name, iterations: ITERATIONS, &)
+  def measure(name, iterations: ITERATIONS, &block)
     # Warmup
-    WARMUP_ITERATIONS.times(&)
+    WARMUP_ITERATIONS.times(&block)
 
     times = []
     allocations = []
     iterations.times do
       GC.start
       GC.disable
-      mem_before = ObjectSpace.count_objects[:TOTAL]
+      # Must be a monotonic counter: count_objects[:TOTAL] counts occupied
+      # slots, so allocations that reuse slots freed by the GC.start above
+      # are invisible (observed as 0-alloc parses and unstable ratios).
+      alloc_before = GC.stat(:total_allocated_objects)
       t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       yield
       t1 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
       GC.enable
-      mem_after = ObjectSpace.count_objects[:TOTAL]
+      alloc_after = GC.stat(:total_allocated_objects)
       times << (t1 - t0)
-      allocations << (mem_after - mem_before)
+      allocations << (alloc_after - alloc_before)
     end
 
     avg_time = times.sum / times.size

data/bench/bench_niso.rb

@@ -11,8 +11,7 @@
 # NOTE: Must run from the niso-jats bundle:
 #   cd $NISO_DIR && bundle exec ruby /path/to/lutaml-model/bench/bench_niso.rb
 
-lutaml_model_root = ENV["LUTAML_MODEL_DIR"] || "/Users/mulgogi/src/lutaml/lutaml-model"
-require "#{lutaml_model_root}/bench/bench_common"
+require_relative "bench_common"
 include BenchCommon
 
 print_header("NISO JATS Benchmark — Journal Article parsing")

data/bench/gate_config.rb

@@ -57,7 +57,10 @@ module GateConfig
       "iso-13849-1MB" => {
         alloc_ratio: 1.05,
         time_ratio: 1.15,
-        absolute_max: 5.0,
+        # GH-hosted ubuntu runners run this fixture at ~12s min_time
+        # (observed across moxml 0.1–0.5); 5.0 never passed there and
+        # fired on every run. 15.0 keeps the 2x-catastrophe safety net.
+        absolute_max: 15.0,
       },
       "din-iso-1.1MB" => {
         alloc_ratio: 1.05,

data/benchmark/serialization_benchmark.rb

@@ -394,7 +394,7 @@ class BenchmarkRunner
     @results[name]
   end
 
-  def run_memory_benchmark(&)
+  def run_memory_benchmark(&block)
     # Force GC before measurement
     GC.start
     GC.compact if GC.respond_to?(:compact)
@@ -403,7 +403,7 @@ class BenchmarkRunner
     profile = RubyProf::Profile.new(measure_mode: RubyProf::ALLOCATIONS)
 
     profile.start
-    10.times(&)
+    10.times(&block)
     result = profile.stop
 
     # Print allocation report
@@ -418,12 +418,12 @@ class BenchmarkRunner
     puts "  Memory profiling skipped: #{e.message}"
   end
 
-  def run_cpu_profile(name, &)
+  def run_cpu_profile(name, &block)
     # ruby-prof 2.0 API: create a profile with wall time measurement
     profile = RubyProf::Profile.new(measure_mode: RubyProf::WALL_TIME)
 
     profile.start
-    ITERATIONS.times(&)
+    ITERATIONS.times(&block)
     result = profile.stop
 
     # Print flat report to console

data/docs/_guides/builder-dsl.adoc

@@ -0,0 +1,127 @@
+---
+title: Builder DSL
+nav_order: 99
+---
+
+= Builder DSL
+:toc:
+:toclevels: 3
+
+The Builder DSL gives any `Lutaml::Model::Serializable` class a block-based
+construction syntax:
+
+[source,ruby]
+----
+person = Person.new do |p|
+  p.name "Ada"
+  p.email "ada@example.com"
+end
+----
+
+It works for every model. For models declared with `ordered` or
+`mixed_content`, the builder also records the order in which attributes were
+mutated so that `to_xml` can emit child elements in the same order.
+
+== Two equivalent syntaxes
+
+Every attribute supports both the *appender* form and the *direct setter* form
+inside the block. They are interchangeable:
+
+[source,ruby]
+----
+# Appender form: looks like a method call with the value as argument
+person = Person.new do |p|
+  p.name "Ada"           # equivalent to p.name = "Ada"
+  p.email "ada@x.org"    # equivalent to p.email = "ada@x.org"
+end
+
+# Direct setter form: looks like a normal assignment
+person = Person.new do |p|
+  p.name = "Ada"
+  p.email = "ada@x.org"
+end
+----
+
+Both snippets produce identical `to_xml`, `to_json`, etc. Use whichever reads
+better in context.
+
+=== Collections
+
+Collection attributes accept both forms too:
+
+[source,ruby]
+----
+group = Group.new do |g|
+  # Append one item at a time:
+  g.member(person1)
+  g.member(person2)
+
+  # Or assign the whole collection at once:
+  g.members = [person1, person2, person3]
+end
+----
+
+The wholesale assignment records one order-entry per item, so the resulting
+`element_order` length matches the number of serialized child elements.
+
+== Order tracking and serialization
+
+The builder tracks call order only when *all* of the following are true:
+
+1. The instance was constructed via `Klass.new do |x| ... end` (a block was
+   passed).
+2. The XML mapping is declared with `ordered` or `mixed_content`.
+
+When tracking is active, every mutation (via either syntax) is appended to the
+instance's `element_order`. `to_xml` then iterates `element_order` to emit
+child elements in the order they were set.
+
+When tracking is *not* active (no block, or the model is neither `ordered` nor
+`mixed_content`), `element_order` stays `nil` and `to_xml` emits elements in
+declaration order.
+
+=== Equivalence with `.tap`
+
+The block form is the only way to enable tracking. Constructing the instance
+separately and mutating it afterwards does not enable tracking:
+
+[source,ruby]
+----
+# Tracking active:
+item = Item.new { |i| i.b = "first"; i.a = "second" }
+item.element_order.map(&:name) # => ["b", "a"]
+
+# Tracking NOT active:
+item = Item.new
+item.b = "first"
+item.a = "second"
+item.element_order # => nil
+# Falls back to declaration order for serialization.
+----
+
+If you want call-order preservation, use the block form.
+
+== No silent data loss (invariant)
+
+The serializer guarantees that every attribute with a non-default value appears
+in the serialized output, regardless of which syntax was used to set it.
+
+This is enforced by `OrderedApplier#apply_remaining_rules`: any element-typed
+attribute not represented in `element_order` is emitted in declaration order
+after the tracked entries. This is a safety net on top of the builder's own
+tracking, so that future code paths (new mutation helpers, attribute merge
+operations, etc.) cannot silently drop user data.
+
+If you find an attribute missing from `to_xml`, the right answer is to fix the
+mutation path so it records into `element_order`. The safety net guarantees
+correctness; it does not guarantee order.
+
+== Performance notes
+
+For models that are neither `ordered` nor `mixed_content`, the builder does
+not allocate any `Lutaml::Xml::Element` order-tracking objects. The check is
+`@__order_tracking__` (a boolean), and the recording helpers are no-ops.
+
+The check is also a no-op for `ordered`/`mixed_content` models constructed
+without a block. This keeps the common case (`Klass.from_xml(xml)` followed
+by `to_xml`) free of tracking overhead.

data/docs/_guides/value-transformations.adoc

@@ -194,6 +194,33 @@ Use Custom Value Type classes when:
 * **Testable** - Easy to unit test in isolation
 * **Maintainable** - Centralized logic, easier to modify
 
+==== Whole-Value Types (Scalar or List)
+
+A custom value type on a non-collection attribute receives the raw value
+whole — including Arrays — so a type may legitimately wrap a scalar *or* a
+list in a single slot:
+
+[source,ruby]
+----
+class LiteralValue < Lutaml::Model::Type::Value
+end
+
+class LiteralDoc < Lutaml::Model::Serializable
+  attribute :v, LiteralValue
+  key_value do
+    map "v", to: :v
+  end
+end
+
+LiteralDoc.from_yaml("v: hello").v   # => "hello"
+LiteralDoc.from_yaml("v: [a, b]").v  # => ["a", "b"]
+----
+
+Built-in scalar types keep the guidance error: an Array arriving on a
+non-collection attribute of a built-in type still raises
+`CollectionTrueMissingError` ("May be `collection: true` is missing").
+Declare `collection: true` for list attributes.
+
 ==== Complete Example: Bidirectional Date Formats
 
 [source,ruby]