lutaml-model 0.8.22 → 0.8.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a30fcd552dca587769736a81de33b66909c592cbc5ed40f696d34fbaf7de887f
-  data.tar.gz: b15506fd1398cad525dcac0a624166cdc23dedf7faa3e282b1aae10c583b405a
+  metadata.gz: 22cdfc7334bab60076fc98d5153c5770789f2670dc41eeabfee4df3dc6265f99
+  data.tar.gz: fcb7ed45d08960bc739e7b0401771c96cc295a79f0d5236d60c0b8c7edfc54bb
 SHA512:
-  metadata.gz: 061ea9253cc7e425f9591e5f57407935eb6b52b1ee69fc5b289b672a0109f8aa3850097d0dd3971613b6010c5e8d83b5425e3447bebe0ae6724916fbdc7a3173
-  data.tar.gz: 9280bc8adfdeaa2e6167c57379d0d40a7c8c27a4dffb420c8f8b6468b893df8ae72207d5fddef2885d4954ba4c45918a1f9cd3746ef2194aed3b09bae46b19f9
+  metadata.gz: c2642f2aba35a1eff18d1cc69c3dd44c95f88c80ebb8b76937c10202f0f2527e9c8365be6730fdbd69ee34b44641707714e4d6e0bd2c1cb062176a8d735b7398
+  data.tar.gz: 5cb5c0079ac4d8cb578cab080641e2d4f3d6a6445c1f212080aba556133b8b707afdf86a8508a4df488c859b3fabbe52adf26f324ddaecd1988f4d79338dc2b9

data/docs/_guides/xml-mapping.adoc

@@ -717,6 +717,37 @@ end
 ----
 ====
 
+===== Mapping several element names to one attribute
+
+Several `map_element` rules may target the same collection attribute to
+accept multiple spellings of one element (e.g. a legacy and a modern
+name). Parsing merges the content of every spelling **in document
+order**; serialization emits the value once, under the **first declared**
+spelling.
+
+[source,ruby]
+----
+class Editorial < Lutaml::Model::Serializable
+  attribute :groups, Group, collection: true
+
+  xml do
+    element "metadata"
+    map_element "editorial-group", to: :groups
+    map_element "editorialgroup", to: :groups # legacy spelling
+  end
+end
+
+Editorial.from_xml(
+  "<metadata><editorialgroup>…</editorialgroup><editorial-group>…</editorial-group></metadata>"
+).groups
+# => [group(legacy), group(modern)] — document order
+----
+
+NOTE: The merge applies to plain element rules on collection attributes.
+Rules with custom deserialization methods, `raw`, `content`, or `cdata`
+are not merged — each still assigns separately, last rule winning as
+before.
+
 ===== Using elements in different namespaces
 
 ====== General

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

@@ -17,6 +17,13 @@ module Lutaml
         end
 
         # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
+        # Oj has its own option namespace and its own escape_mode. Handing it
+        # the stdlib generator's options overrides that configuration, so it
+        # takes none of them -- which is what it received before.
+        def ignores_generator_options?
+          true
+        end
+
         def to_json(*args)
           require "oj"
           # Handle KeyValueElement input (new symmetric architecture)

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../generator_options"
 
 module Lutaml
   module Json
@@ -9,12 +10,16 @@ module Lutaml
         FORMAT_SYMBOL = :json
 
         def self.parse(json, _options = {})
-          JSON.parse(json, create_additions: false)
+          JSON.parse(json)
         end
 
-        def to_json(*args)
-          options = args.first || {}
+        # This adapter hands its payload to the stdlib generator, so a
+        # JSON::State carrying the outer formatting is meaningful here.
+        def accepts_generator_state?
+          true
+        end
 
+        def to_json(*args)
           # Handle KeyValueElement input (new symmetric architecture)
           attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
                                       # Unwrap __root__ wrapper to get actual content
@@ -24,10 +29,17 @@ module Lutaml
                                       @attributes
                                     end
 
+          unless GeneratorOptions.lutaml_options?(args.first)
+            return JSON.generate(attributes_to_serialize, args.first)
+          end
+
+          options = args.first || {}
+          generator_options = GeneratorOptions.filter(options)
+
           if options[:pretty]
-            JSON.pretty_generate(attributes_to_serialize, *args)
+            JSON.pretty_generate(attributes_to_serialize, generator_options)
           else
-            JSON.generate(attributes_to_serialize, *args)
+            JSON.generate(attributes_to_serialize, generator_options)
           end
         end
       end

data/lib/lutaml/json/generator_options.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Lutaml
+  module Json
+    # Filters the options LutaML threads through serialization down to the
+    # subset the JSON generator accepts.
+    #
+    # json 2.x silently ignored unknown generator options; json 3.0 raises
+    # ArgumentError on them, so LutaML's own options (:register, :pretty and
+    # any caller-supplied extras) have to be stripped before they reach
+    # JSON.generate.
+    module GeneratorOptions
+      # Options the generator accepts on both json 2.x and 3.x. Measured
+      # against 2.9.1, 2.15.2, 2.19.9, 2.20.0, 2.21.1, 2.21.2 and 3.0.0.
+      # :escape_slash is NOT here because json 3.0 removed it; on 2.x it still
+      # arrives via DERIVED_PERMITTED. :allow_duplicate_key IS here because the
+      # generator accepts it on every version while JSON::State never exposed
+      # it as an accessor, so the derived half alone would miss it.
+      BASE_PERMITTED = %i[
+        allow_duplicate_key allow_nan array_nl as_json ascii_only
+        buffer_initial_length depth indent max_nesting object_nl script_safe
+        sort_keys space space_before strict
+      ].freeze
+
+      # Additive, so a json release that adds an option needs no change here.
+      # Opal's JSON shim has no State class, hence the guard.
+      DERIVED_PERMITTED =
+        if defined?(::JSON::State)
+          accessors = ::JSON::State.instance_methods(false).grep(/\A[a-z_][a-z0-9_]*=\z/)
+          accessors.map { |name| name.to_s.chomp("=").to_sym }
+        else
+          []
+        end.freeze
+
+      PERMITTED = (BASE_PERMITTED | DERIVED_PERMITTED).freeze
+
+      # json 3.0 removed :escape_slash, which was only ever an alias of
+      # :script_safe. Dropping it would silently stop escaping slashes, so it
+      # is translated instead of discarded.
+      RENAMED = { escape_slash: :script_safe }.freeze
+
+      def self.filter(options)
+        return {} unless options.is_a?(::Hash)
+
+        options.each_with_object({}) do |(key, value), kept|
+          key = RENAMED.fetch(key, key) unless PERMITTED.include?(key)
+          kept[key] = value if PERMITTED.include?(key)
+        end
+      end
+
+      # Ruby's JSON generator calls #to_json with a JSON::State whenever a
+      # document is nested inside another JSON.generate call. That is the
+      # generator's own state, not a LutaML options hash, and json 3.0 removed
+      # JSON::State#[], so it must never be read like one.
+      def self.lutaml_options?(argument)
+        argument.nil? || argument.is_a?(::Hash)
+      end
+    end
+  end
+end

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

@@ -14,7 +14,7 @@ module Lutaml
             next if line.strip.empty?
 
             begin
-              results << JSON.parse(line, create_additions: false)
+              results << JSON.parse(line)
             rescue JSON::ParserError => e
               warn "Skipping invalid line: #{e.message}"
             end

data/lib/lutaml/jsonld/adapter.rb

@@ -1,21 +1,29 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../json/generator_options"
 
 module Lutaml
   module JsonLd
     class Adapter < Lutaml::KeyValue::Document
       def self.parse(jsonld_string, _options = {})
-        JSON.parse(jsonld_string, create_additions: false)
+        JSON.parse(jsonld_string)
       end
 
       def to_jsonld(*args)
-        options = args.first || {}
         data = @attributes
+
+        unless Lutaml::Json::GeneratorOptions.lutaml_options?(args.first)
+          return JSON.generate(data, args.first)
+        end
+
+        options = args.first || {}
+        generator_options = Lutaml::Json::GeneratorOptions.filter(options)
+
         if options[:pretty]
-          JSON.pretty_generate(data, *args)
+          JSON.pretty_generate(data, generator_options)
         else
-          JSON.generate(data, *args)
+          JSON.generate(data, generator_options)
         end
       end
     end

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

@@ -21,6 +21,13 @@ module Lutaml
           end
 
           # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
+          # Oj has its own option namespace and its own escape_mode. Handing it
+          # the stdlib generator's options overrides that configuration, so it
+          # takes none of them -- which is what it received before.
+          def ignores_generator_options?
+            true
+          end
+
           def to_json(*args)
             require "oj"
             # Handle KeyValueElement input (new symmetric architecture)

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "json"
+require_relative "../../../json/generator_options"
 
 # Backward compatibility - delegates to Lutaml::Json::Adapter
 # @deprecated Use Lutaml::Json::Adapter::StandardAdapter instead
@@ -13,12 +14,16 @@ module Lutaml
           FORMAT_SYMBOL = :json
 
           def self.parse(json, _options = {})
-            JSON.parse(json, create_additions: false)
+            JSON.parse(json)
           end
 
-          def to_json(*args)
-            options = args.first || {}
+          # This adapter hands its payload to the stdlib generator, so a
+          # JSON::State carrying the outer formatting is meaningful here.
+          def accepts_generator_state?
+            true
+          end
 
+          def to_json(*args)
             # Handle KeyValueElement input (new symmetric architecture)
             attributes_to_serialize = if @attributes.is_a?(Lutaml::KeyValue::DataModel::Element)
                                         # Unwrap __root__ wrapper to get actual content
@@ -28,10 +33,17 @@ module Lutaml
                                         @attributes
                                       end
 
+            unless Lutaml::Json::GeneratorOptions.lutaml_options?(args.first)
+              return JSON.generate(attributes_to_serialize, args.first)
+            end
+
+            options = args.first || {}
+            generator_options = Lutaml::Json::GeneratorOptions.filter(options)
+
             if options[:pretty]
-              JSON.pretty_generate(attributes_to_serialize, *args)
+              JSON.pretty_generate(attributes_to_serialize, generator_options)
             else
-              JSON.generate(attributes_to_serialize, *args)
+              JSON.generate(attributes_to_serialize, generator_options)
             end
           end
         end

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

@@ -15,7 +15,7 @@ module Lutaml
               next if line.strip.empty?
 
               begin
-                results << JSON.parse(line, create_additions: false)
+                results << JSON.parse(line)
               rescue JSON::ParserError => e
                 warn "Skipping invalid line: #{e.message}"
               end

data/lib/lutaml/model/collection.rb

@@ -308,6 +308,10 @@ module Lutaml
         end
 
         def to(format, instance, options = {})
+          # Wrap before the branch, not inside it: only XML reaches the
+          # unwrapped path today, but a raw JSON::State must never survive
+          # into either arm.
+          options = Lutaml::Model::Serialize.wrap_generator_state(options)
           mappings = mappings_for(format)
 
           if mappings.no_root? && collection_unwrapped_to?(format)
@@ -456,6 +460,7 @@ lutaml_register: Lutaml::Model::Config.default_register)
       end
 
       def to_format(format, options = {})
+        options = Lutaml::Model::Serialize.wrap_generator_state(options)
         super(format, options.merge(collection: true))
       end
 

data/lib/lutaml/model/serialization_adapter.rb

@@ -17,7 +17,7 @@ module Lutaml
       end
 
       def self.parse(data, _options = {})
-        document_class.parse(data, create_additions: false)
+        document_class.parse(data)
       end
     end
   end

data/lib/lutaml/model/serialize/format_conversion.rb

@@ -192,24 +192,55 @@ module Lutaml
         #   is always preserved when available, regardless of this option.
         # @return [String] The serialized output
         def to(format, instance, options = {})
+          # Ruby's JSON generator hands #to_json its own JSON::State rather
+          # than an options hash. It carries no LutaML options, but it does
+          # carry the surrounding indent context, so it is forwarded to the
+          # adapter unchanged instead of being read like a Hash -- json 3.0
+          # removed JSON::State#[].
+          options = Serialize.wrap_generator_state(options)
+          generator_state = options.delete(Serialize::GENERATOR_STATE_KEY)
+
           Instrumentation.instrument(:to, model: name, format: format) do
-            adapter_override = options.is_a?(Hash) && options.delete(:adapter)
-            if adapter_override && options.is_a?(Hash)
-              options[:_adapter_override] =
-                true
-            end
+            adapter_override = options.delete(:adapter)
+            options[:_adapter_override] = true if adapter_override
             value = public_send(:"as_#{format}", instance, options)
             adapter = resolve_adapter(format, adapter_override)
 
             # Hook for format-specific options preparation (e.g., XML prefix/namespace/declaration)
             options = prepare_to_options(format, instance, options)
 
-            adapter.new(value, register: options[:register]).public_send(
-              :"to_#{format}", options
+            document = adapter.new(value, register: options[:register])
+
+            document.public_send(
+              :"to_#{format}",
+              forward_options(document, generator_state, options),
             )
           end
         end
 
+        # Main's behaviour differs per ADAPTER, not per option, so this follows
+        # the adapter rather than trying to translate option names:
+        #   stdlib  honours script_safe / ascii_only / pretty -> give it the state
+        #   Oj      ignores them all and uses its own escape_mode -> give it none
+        #   others  reach the stdlib generator underneath -> give them the options
+        def forward_options(document, generator_state, options)
+          return options if generator_state.nil?
+
+          if declares?(document, :accepts_generator_state?)
+            generator_state
+          elsif declares?(document, :ignores_generator_options?)
+            options
+          elsif generator_state.respond_to?(:to_h)
+            options.merge(generator_state.to_h)
+          else
+            options
+          end
+        end
+
+        def declares?(document, predicate)
+          document.respond_to?(predicate) && document.public_send(predicate)
+        end
+
         # Hook for format-specific options preparation before serialization.
         # XML overrides to handle prefix, namespace overrides, declaration plan.
         #

data/lib/lutaml/model/serialize.rb

@@ -225,7 +225,25 @@ module Lutaml
         self.class.as_yaml(self)
       end
 
+      # Ruby's JSON generator hands #to_json its own JSON::State instead of an
+      # options hash. It carries no LutaML options, but it does carry the
+      # surrounding indent context, so it travels IN BAND under a private key
+      # rather than replacing the options hash. Wrapping rather than returning
+      # early keeps every later step -- register propagation, root-mapping
+      # validation, Collection's `collection: true` merge -- working on a real
+      # Hash. json 3.0 removed JSON::State#[] and rejects unknown keys in
+      # State#merge, so nothing may treat it as a Hash.
+      GENERATOR_STATE_KEY = :_generator_state
+
+      def self.wrap_generator_state(options)
+        return options if options.is_a?(::Hash)
+
+        { GENERATOR_STATE_KEY => options }
+      end
+
       def to_format(format, options = {})
+        options = Lutaml::Model::Serialize.wrap_generator_state(options)
+
         # Hook for format-specific validation (e.g., XML root mapping check)
         validate_root_mapping!(format, options)
 

data/lib/lutaml/model/transformation.rb

@@ -37,9 +37,14 @@ module Lutaml
         @format = format
         @register = register
         @compiled_rules = compile_rules(mapping_dsl)
+        after_compile
         freeze
       end
 
+      # Hook for format subclasses to derive rule-set-level data after
+      # compilation, before the transformation is frozen and shared.
+      def after_compile; end
+
       # Transform a model instance into format-specific representation
       #
       # @abstract Subclasses must implement this method

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.22"
+    VERSION = "0.8.23"
   end
 end

data/lib/lutaml/xml/mapping.rb

@@ -1071,6 +1071,30 @@ module Lutaml
         result
       end
 
+      # lutaml-model#765: plain element rules grouped by target attribute
+      # name, for spelling-tolerance mapping (several element names feeding
+      # one attribute). Cached per register so the parse hot path only pays
+      # a hash lookup. Grouping uses rule-level properties only — the
+      # transform applies the collection-attribute filter.
+      #
+      # @return [Hash{Symbol, String => Array<MappingRule>}]
+      def plain_element_rules_by_attr(register_id = nil)
+        reg_key = register_id || :default
+        @plain_element_rules_by_attr ||= {}
+        @plain_element_rules_by_attr[reg_key] ||= begin
+          grouped = {}
+          mappings(reg_key).each do |r|
+            next if r.attribute? || r.raw_mapping? || r.content_mapping? ||
+              r.cdata || r.has_custom_method_for_deserialization? ||
+              (r.transform.is_a?(Hash) && !r.transform.empty?) ||
+              r.transform.is_a?(Class)
+
+            (grouped[r.to] ||= []) << r
+          end
+          grouped
+        end
+      end
+
       def importable_mappings
         @importable_mappings ||= []
       end

data/lib/lutaml/xml/model_transform.rb

@@ -258,6 +258,18 @@ module Lutaml
           end
         end
 
+        # lutaml-model#765: several plain element rules may target one
+        # collection attribute (spelling tolerance, e.g. editorial-group vs
+        # editorialgroup). The first rule of such a group performs matching
+        # widened to every spelling so content merges in document order;
+        # the remaining rules are no-ops so their assignment cannot
+        # silently overwrite the merged value.
+        # Grouping is cached on the mapping DSL (per register); only the
+        # collection filter runs here.
+        grouped_plain_rules = xml_mapping.plain_element_rules_by_attr(
+          effective_register,
+        )
+
         mappings.each do |rule|
           # Performance: Cache rule properties accessed multiple times
           rule.name
@@ -268,6 +280,11 @@ module Lutaml
           attr = attribute_for_rule(rule)
           next if attr&.derived?
 
+          if (group = grouped_plain_rules[rule_to]) &&
+              group.size > 1 && attr&.collection? && !group.first.equal?(rule)
+            next
+          end
+
           raise "Attribute '#{rule_to}' not found in #{context}" unless valid_rule?(
             rule, attr
           )
@@ -285,6 +302,26 @@ module Lutaml
                     doc.root.inner_xml
                   elsif rule.content_mapping?
                     rule.cdata ? doc.cdata : doc.text
+                  elsif (group = grouped_plain_rules[rule_to]) &&
+                      group.size > 1 && attr&.collection?
+                    # First rule of a #765 group: match every spelling of
+                    # the group so the children merge in document order.
+                    if child_names_set &&
+                        group.drop(1).none? do |s|
+                          child_matches_rule?(s, child_names_set,
+                                              default_namespace)
+                        end && !child_matches_rule?(rule, child_names_set,
+                                                    default_namespace)
+                      ::Lutaml::Model::UninitializedClass.instance
+                    else
+                      extra_names = group.drop(1).flat_map do |s|
+                        resolve_rule_names_with_type(s, attr, new_opts,
+                                                     effective_register,
+                                                     attr&.type(effective_register))
+                      end
+                      value_for_rule(session, rule, new_opts, attr,
+                                     extra_names)
+                    end
                   elsif child_names_set && !rule.attribute? &&
                       !child_matches_rule?(rule, child_names_set,
                                            default_namespace)
@@ -551,7 +588,8 @@ _effective_register)
         nil
       end
 
-      def value_for_rule(session, rule, options, cached_attr = nil)
+      def value_for_rule(session, rule, options, cached_attr = nil,
+                         extra_rule_names = nil)
         doc = session.doc
         instance = session.instance
         instance_is_serialize = session.instance_is_serialize
@@ -576,6 +614,12 @@ _effective_register)
                        resolve_rule_names_with_type(rule, attr, options,
                                                     effective_register, attr_type)
                      end
+        # lutaml-model#765: widened matching for the first rule of a
+        # shared-attribute group — children of sibling spellings must be
+        # selected too, in document order. Deduped: sibling resolution can
+        # yield the same spelling twice, and the child index would then
+        # return the same children again.
+        rule_names = rule_names.concat(extra_rule_names).uniq if extra_rule_names
 
         return value_for_xml_attribute(doc, rule, rule_names) if rule.attribute?
 
@@ -643,6 +687,13 @@ _effective_register)
             children = nil # fall through to select for alias matching
           else
             children = indexed.flatten(1)
+            # #765 widened matching: rule_names spans several spellings, so
+            # the flatten above yields rule-name order; restore document
+            # order for the merged group.
+            if extra_rule_names
+              position = element_children.each_with_index.to_h
+              children = children.sort_by { |c| position[c] }
+            end
           end
         else
           children = nil

data/lib/lutaml/xml/transformation.rb

@@ -264,6 +264,8 @@ module Lutaml
           root, model_instance, options,
           compiled_rules, model_class, register_id
         ) do |action, rule, value, set_xsi_nil|
+          next if action == :apply_rule && duplicate_element_rules[rule]
+
           rule_options = options.merge(current_model: model_instance)
           case action
           when :apply_rule
@@ -291,6 +293,32 @@ module Lutaml
       # @param root [XmlElement] Root element
       # @param model_instance [Object] The model instance
       # @param options [Hash] Options
+      # Reader for the precomputed skip set (#765).
+      def duplicate_element_rules
+        @duplicate_element_rules
+      end
+
+      # lutaml-model#765: several element rules may target one attribute
+      # (spelling tolerance, e.g. editorial-group vs editorialgroup). The
+      # extra spellings exist for parse tolerance only — serialization
+      # emits the value once, under the first declared spelling. Derived
+      # once at compile time (transformations are frozen and shared).
+      def after_compile
+        seen = {}
+        @duplicate_element_rules = {}
+        compiled_rules.each do |rule|
+          next unless rule.option(:mapping_type) == :element
+
+          key = rule.attribute_name.to_s
+          if seen.key?(key)
+            @duplicate_element_rules[rule] = true
+          else
+            seen[key] = true
+          end
+        end
+        @duplicate_element_rules.freeze
+      end
+
       def apply_standard_rules(root, model_instance, options)
         attr_order = model_instance.is_a?(Lutaml::Model::Serialize) &&
           model_instance.attribute_order
@@ -303,6 +331,7 @@ module Lutaml
 
         rules.each do |rule|
           next unless valid_mapping?(rule, options)
+          next if duplicate_element_rules[rule]
 
           rule_options = options.merge(current_model: model_instance)
           apply_rule(root, rule, model_instance, rule_options, model_class,

data/spec/lutaml/json/adapter/standard_adapter_spec.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "lutaml/json/adapter/standard_adapter"
+
+RSpec.describe Lutaml::Json::Adapter::StandardAdapter do
+  let(:attributes) { { "name" => "John", "age" => 30 } }
+
+  describe ".parse" do
+    # json 3.0 removed create_additions and now raises ArgumentError on any
+    # unknown keyword, so the parser must be called without it.
+    it "parses without passing removed generator keywords to the json gem" do
+      expect(described_class.parse('{"name":"John","age":30}'))
+        .to eq(attributes)
+    end
+  end
+
+  describe "#to_json" do
+    subject(:document) { described_class.new(attributes) }
+
+    it "serializes with no options" do
+      expect(document.to_json).to eq('{"name":"John","age":30}')
+    end
+
+    # :register and :pretty are LutaML's own options. json 2.x ignored unknown
+    # options; json 3.0 raises ArgumentError, so they must be stripped before
+    # they reach JSON.generate.
+    it "strips LutaML options that the json generator does not accept" do
+      expect(document.to_json(register: :default_register))
+        .to eq('{"name":"John","age":30}')
+    end
+
+    it "strips LutaML options when generating pretty output" do
+      expect(document.to_json(pretty: true, register: :default_register))
+        .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+    end
+
+    # An ALLOWLIST and a denylist of LutaML's own option names behave
+    # identically for :register and :pretty. Only a key nobody enumerated
+    # tells them apart -- and json 3.0 raises on it.
+    it "strips a caller option nobody enumerated" do
+      expect(document.to_json(some_unknown_option: 1))
+        .to eq('{"name":"John","age":30}')
+    end
+
+    # json 3.0 removed :escape_slash. Dropping it would silently stop escaping
+    # slashes; it is the old alias of :script_safe, so it is translated.
+    it "honours escape_slash on every json version" do
+      expect(described_class.new({ "a" => "x/y" }).to_json(escape_slash: true))
+        .to eq('{"a":"x\\/y"}')
+    end
+
+    # The filter is an allowlist, not a passthrough: genuine generator options
+    # must still reach JSON.generate.
+    it "forwards options the json generator does accept" do
+      expect(document.to_json(register: :default_register, space: " "))
+        .to eq('{"name": "John","age": 30}')
+    end
+  end
+
+  describe "nesting inside another JSON.generate call" do
+    subject(:document) { described_class.new(attributes) }
+
+    # Ruby's generator hands #to_json a JSON::State, not an options hash.
+    # json 3.0 removed JSON::State#[], so reading :pretty off it raises.
+    it "serializes when nested in a Hash passed to JSON.generate" do
+      expect(JSON.generate({ "doc" => document }))
+        .to eq('{"doc":{"name":"John","age":30}}')
+    end
+
+    it "serializes when nested in an Array passed to JSON.generate" do
+      expect(JSON.generate([document])).to eq('[{"name":"John","age":30}]')
+    end
+
+    # A DEFAULT state renders compact, which is also what a DISCARDED state
+    # produces, so the two examples above cannot tell them apart. These carry
+    # formatting, so dropping the state changes the output.
+    it "inherits the outer indent when nested in a pretty Hash" do
+      expect(JSON.pretty_generate({ "doc" => document }))
+        .to eq(%({\n  "doc": {\n    "name": "John",\n    "age": 30\n  }\n}))
+    end
+
+    it "inherits the outer indent when nested in a pretty Array" do
+      expect(JSON.pretty_generate([document]))
+        .to eq(%([\n  {\n    "name": "John",\n    "age": 30\n  }\n]))
+    end
+
+    it "honours a configured JSON::State handed to #to_json directly" do
+      # A DEFAULT state renders compact, which is also what a discarded state
+      # produces -- so the state has to carry formatting for this to mean
+      # anything.
+      state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+      expect(document.to_json(state))
+        .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+    end
+  end
+
+  describe Lutaml::Json::GeneratorOptions do
+    # The derived half of the allowlist reads JSON::State, which Opal's JSON
+    # shim does not define. BASE_PERMITTED is what the filter falls back to
+    # there, so it has to stand on its own.
+    # BASE_PERMITTED is the whole allowlist on Opal, whose JSON shim has no
+    # State class for DERIVED_PERMITTED to read. So it has to stand alone
+    # against the real generator, not merely be a subset of something larger.
+    it "permits only options the running generator actually accepts" do
+      rejected = described_class::BASE_PERMITTED.reject do |key|
+        JSON.generate({ "a" => 1 }, key => nil)
+        true
+      rescue ArgumentError => e
+        # "unknown keyword" means the generator does not know this option at
+        # all. Any other complaint -- a type error about the nil value we
+        # passed -- means it knows the option and only dislikes the value.
+        !e.message.include?("unknown keyword")
+      rescue StandardError
+        true
+      end
+
+      expect(rejected).to eq([])
+    end
+
+    # Opal's JSON shim defines no State class, so DERIVED_PERMITTED is empty
+    # there and the whole module must still load. Asserting that
+    # BASE_PERMITTED contains some symbols does not exercise the guard; only
+    # loading the file with JSON::State absent does.
+    it "loads and still permits the base set when JSON::State is absent" do
+      hide_const("JSON::State")
+
+      mod = Module.new
+      mod.module_eval(
+        File.read(File.expand_path("../../../../lib/lutaml/json/generator_options.rb", __dir__)),
+      )
+      permitted = mod.const_get(:Lutaml).const_get(:Json)
+        .const_get(:GeneratorOptions)::PERMITTED
+
+      expect(permitted).to eq(described_class::BASE_PERMITTED)
+    end
+
+    it "carries the formatting options pretty output depends on" do
+      expect(described_class::BASE_PERMITTED)
+        .to include(:indent, :object_nl, :space, :space_before)
+    end
+
+    it "rejects a non-Hash options argument" do
+      expect(described_class.filter(nil)).to eq({})
+    end
+
+    it "treats nil as LutaML options" do
+      expect(described_class.lutaml_options?(nil)).to be(true)
+    end
+
+    it "treats a Hash as LutaML options" do
+      expect(described_class.lutaml_options?({ pretty: true })).to be(true)
+    end
+
+    it "does not treat a JSON::State as LutaML options" do
+      expect(described_class.lutaml_options?(JSON::State.new)).to be(false)
+    end
+  end
+end

data/spec/lutaml/jsonld/adapter_spec.rb

@@ -43,4 +43,23 @@ RSpec.describe Lutaml::JsonLd::Adapter do
     round_tripped = JSON.parse(result)
     expect(round_tripped).to eq(jsonld_hash.transform_keys(&:to_s))
   end
+
+  describe "a JSON::State handed to #to_jsonld" do
+    subject(:document) { described_class.new({ "@id" => "urn:x", "n" => 1 }) }
+
+    # Ruby's generator only ever calls #to_json, so a state reaches #to_jsonld
+    # only from a direct caller. json 3.0 removed JSON::State#[], so the state
+    # must be forwarded to the payload rather than read as an options hash.
+    it "honours a state that carries formatting" do
+      state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+
+      expect(document.to_jsonld(state))
+        .to eq(%({\n  "@id": "urn:x",\n  "n": 1\n}))
+    end
+
+    it "renders compactly for a default state" do
+      expect(document.to_jsonld(JSON::State.new))
+        .to eq('{"@id":"urn:x","n":1}')
+    end
+  end
 end

data/spec/lutaml/model/collection_spec.rb

@@ -644,7 +644,7 @@ RSpec.describe Lutaml::Model::Collection do
       collection = title_collection_class.from_json(json_data)
 
       # JSON.parse should only be called once on the main array, not on individual strings
-      expect(JSON).to have_received(:parse).once.with(json_data, anything)
+      expect(JSON).to have_received(:parse).once.with(json_data)
       expect(collection.titles.map(&:content)).to eq(["Title One", "Title Two",
                                                       "Title Three"])
     end

data/spec/lutaml/model/collection_state_nesting_spec.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# A Collection overrides #to_format and merges `collection: true` into the
+# options BEFORE the base implementation runs. JSON::State#merge is #configure,
+# which rejects unknown keys on json 3.0, so the state has to be wrapped first.
+RSpec.describe "a collection nested inside JSON.generate" do
+  before do
+    stub_const("NestedItem", Class.new(Lutaml::Model::Serializable) do
+      attribute :n, :string
+    end)
+    stub_const("NestedItems", Class.new(Lutaml::Model::Collection) do
+      instances :items, NestedItem
+    end)
+  end
+
+  let(:collection) { NestedItems.new([NestedItem.new(n: "a")]) }
+
+  it "serializes inside a Hash" do
+    expect(JSON.generate({ "c" => collection })).to eq('{"c":[{"n":"a"}]}')
+  end
+
+  it "inherits the outer indent inside a pretty Hash" do
+    expect(JSON.pretty_generate({ "c" => collection }))
+      .to eq(%({\n  "c": [\n    {\n      "n": "a"\n    }\n  ]\n}))
+  end
+
+  # The class-level entry point normalises separately from the instance one,
+  # and deleting that normaliser leaves every instance example green.
+  it "normalises a state passed to the class-level entry point" do
+    # array_nl is what puts the newlines in an array; without it the state
+    # is not a pretty state at all and the example proves nothing.
+    state = JSON::State.new(indent: "  ", object_nl: "\n", array_nl: "\n",
+                            space: " ")
+
+    expect(NestedItems.to_json(collection, state))
+      .to eq(%([\n  {\n    "n": "a"\n  }\n]))
+  end
+
+  it "still serializes directly" do
+    expect(collection.to_json).to eq('[{"n":"a"}]')
+  end
+end

data/spec/lutaml/model/generator_defaults_spec.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "oj"
+require "multi_json"
+
+# What a nested model should do with the outer generator's options differs per
+# ADAPTER, not per option. Reference values are unmodified main on json 2.21.2.
+#
+#   stdlib  honours script_safe / ascii_only / pretty  -> receives the state
+#   Oj      ignores them and uses its own escape_mode  -> receives none of them
+#
+# Four earlier attempts at this got it wrong by reasoning about option names
+# instead of measuring each adapter, so every row here is a measured cell.
+RSpec.describe "generator options reaching a nested model" do
+  before do
+    stub_const("EscapeProbe", Class.new(Lutaml::Model::Serializable) do
+      attribute :s, :string
+    end)
+  end
+
+  let(:model) { EscapeProbe.new(s: "</script>é") }
+
+  describe "the stdlib adapter" do
+    it "honours script_safe" do
+      expect(JSON.generate({ "m" => model }, script_safe: true))
+        .to eq('{"m":{"s":"<\\/script>é"}}')
+    end
+
+    it "honours ascii_only" do
+      expect(JSON.generate({ "m" => model }, ascii_only: true))
+        .to eq('{"m":{"s":"</script>\\u00e9"}}')
+    end
+
+    it "honours the outer indent" do
+      expect(JSON.pretty_generate({ "m" => model }))
+        .to eq(%({\n  "m": {\n    "s": "</script>é"\n  }\n}))
+    end
+  end
+
+  describe "the Oj adapter" do
+    around do |example|
+      previous = Oj.default_options
+      Oj.default_options = { escape_mode: :xss_safe }
+      example.run
+      Oj.default_options = previous
+    end
+
+    # Oj must keep its OWN escaping. Forwarding the generator's options -- all
+    # of them, only the caller-set ones, or just ascii_only -- each reset
+    # escape_mode and silently emitted a literal </script>.
+    it "keeps its configured escape_mode when no option is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model })
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+
+    it "keeps its configured escape_mode when ascii_only is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model }, ascii_only: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+
+    it "keeps its configured escape_mode when script_safe is passed" do
+      result = Lutaml::Model::Config.with_adapter(json: :oj) do
+        JSON.generate({ "m" => model }, script_safe: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"\\u003c\\/script\\u003e\\u00e9"}}')
+    end
+  end
+
+  # MultiJson's json_gem backend IS the stdlib generator, so unlike Oj it does
+  # honour these options and must still receive them. That BACKEND cannot run
+  # under json 3.0 -- it sends create_additions, which json removed -- so these
+  # are asserted on the versions where it works. multi_json itself is fine
+  # under json 3.0 on its Oj backend; only json_gem is affected.
+  describe "the MultiJson adapter", if: Gem::Version.new(JSON::VERSION) < Gem::Version.new("3.0.0") do
+    before { MultiJson.use(:json_gem) }
+
+    it "still receives script_safe" do
+      result = Lutaml::Model::Config.with_adapter(json: :multi_json) do
+        JSON.generate({ "m" => model }, script_safe: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"<\\/script>é"}}')
+    end
+
+    it "still receives ascii_only" do
+      result = Lutaml::Model::Config.with_adapter(json: :multi_json) do
+        JSON.generate({ "m" => model }, ascii_only: true)
+      end
+
+      expect(result).to eq('{"m":{"s":"</script>\\u00e9"}}')
+    end
+  end
+end

data/spec/lutaml/model/json_state_nesting_spec.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# json 3.0 removed JSON::State#[]. Ruby's generator passes a JSON::State to
+# #to_json whenever a model is nested inside another JSON.generate call, so the
+# model layer must not read option keys off it.
+RSpec.describe "a model nested inside JSON.generate" do
+  before do
+    stub_const("JsonStateNestingModel", Class.new(Lutaml::Model::Serializable) do
+      attribute :name, :string
+      attribute :age, :integer
+    end)
+  end
+
+  let(:model) { JsonStateNestingModel.new(name: "John", age: 30) }
+
+  it "serializes inside a Hash" do
+    expect(JSON.generate({ "person" => model }))
+      .to eq('{"person":{"name":"John","age":30}}')
+  end
+
+  it "serializes inside an Array" do
+    expect(JSON.generate([model])).to eq('[{"name":"John","age":30}]')
+  end
+
+  # The generator's JSON::State carries the surrounding indent context. It has
+  # to reach the adapter, not be discarded, or a nested model silently renders
+  # compact inside an otherwise pretty document. Reference values are the
+  # output of unmodified main on json 2.20.0.
+  it "inherits the surrounding indent inside a pretty Hash" do
+    expect(JSON.pretty_generate({ "person" => model }))
+      .to eq(%({\n  "person": {\n    "name": "John",\n    "age": 30\n  }\n}))
+  end
+
+  it "inherits the surrounding indent inside a pretty Array" do
+    expect(JSON.pretty_generate([model]))
+      .to eq(%([\n  {\n    "name": "John",\n    "age": 30\n  }\n]))
+  end
+
+  it "still honours LutaML's own options when called directly" do
+    expect(model.to_json(pretty: true))
+      .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+  end
+
+  # A non-Hash options argument must be replaced, not merely captured -- a
+  # falsy one (nil, false) previously stayed in place and the next line called
+  # .delete on it.
+  it "does not raise on a nil options argument" do
+    expect(model.to_json(nil)).to eq('{"name":"John","age":30}')
+  end
+
+  it "does not raise on a false options argument" do
+    expect(model.to_json(false)).to eq('{"name":"John","age":30}')
+  end
+
+  # A non-Hash options argument reaches every format, not just JSON, so the
+  # normalisation must not skip format-specific validation on the way past.
+  # A type-only model has no root mapping and must refuse to serialise alone.
+  it "still applies XML root validation to a non-Hash argument" do
+    stub_const("TypeOnlyModel", Class.new(Lutaml::Model::Serializable) do
+      attribute :n, :string
+    end)
+
+    expect { TypeOnlyModel.new(n: "a").to_xml(nil) }
+      .to raise_error(Lutaml::Model::TypeOnlyMappingError)
+  end
+
+  # Every example above goes through an INSTANCE entry point. The class-level
+  # one normalises separately, and deleting that normaliser leaves them all
+  # green.
+  it "normalises a state passed to the class-level entry point" do
+    state = JSON::State.new(indent: "  ", object_nl: "\n", space: " ")
+
+    expect(JsonStateNestingModel.to_json(model, state))
+      .to eq(%({\n  "name": "John",\n  "age": 30\n}))
+  end
+
+  it "leaves non-JSON formats untouched" do
+    expect(model.to_yaml).to eq("---\nname: John\nage: 30\n")
+  end
+end

data/spec/lutaml/xml/shared_element_rules_spec.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# lutaml-model#765: two element rules mapped to one collection attribute
+# (spelling tolerance, e.g. metanorma's editorial-group/editorialgroup).
+# Parse must merge the spellings' content in document order — never drop
+# the first silently — and serialization must emit the value once, under
+# the first declared spelling.
+module SharedElementRulesSpec
+  class Both < Lutaml::Model::Serializable
+    attribute :items, :string, collection: true
+
+    xml do
+      root "r"
+      map_element "a", to: :items
+      map_element "b", to: :items
+    end
+  end
+end
+
+RSpec.describe "multiple element rules on one attribute" do
+  it "appends both spellings in document order" do
+    expect(SharedElementRulesSpec::Both.from_xml("<r><a>one</a><b>two</b></r>").items)
+      .to eq(["one", "two"])
+  end
+
+  it "appends in document order when the second spelling comes first" do
+    expect(SharedElementRulesSpec::Both.from_xml("<r><b>two</b><a>one</a></r>").items)
+      .to eq(["two", "one"])
+  end
+
+  it "keeps document order across interleaved spellings" do
+    xml = "<r><a>1</a><b>2</b><a>3</a><b>4</b></r>"
+    expect(SharedElementRulesSpec::Both.from_xml(xml).items).to eq(%w[1 2 3 4])
+  end
+
+  it "parses a document that only uses the first spelling" do
+    expect(SharedElementRulesSpec::Both.from_xml("<r><a>one</a></r>").items)
+      .to eq(["one"])
+  end
+
+  it "parses a document that only uses the second spelling" do
+    expect(SharedElementRulesSpec::Both.from_xml("<r><b>two</b></r>").items)
+      .to eq(["two"])
+  end
+
+  it "serializes the value once, under the first declared spelling" do
+    xml = SharedElementRulesSpec::Both.new(items: %w[one two]).to_xml
+    expect(xml.scan(/<(a|b)>/).flatten).to eq(%w[a a])
+    expect(xml).to include("<a>one</a>").and include("<a>two</a>")
+  end
+
+  it "round-trips through both spellings without losing content" do
+    doc = SharedElementRulesSpec::Both.from_xml("<r><a>one</a><b>two</b></r>")
+    reparsed = SharedElementRulesSpec::Both.from_xml(doc.to_xml)
+    expect(reparsed.items).to eq(%w[one two])
+  end
+
+  it "keeps the mapping usable when the attribute also has a default" do
+    both = SharedElementRulesSpec::Both.from_xml("<r/>")
+    expect(both.items).to eq([])
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lutaml-model
 version: !ruby/object:Gem::Version
-  version: 0.8.22
+  version: 0.8.23
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-29 00:00:00.000000000 Z
+date: 2026-09-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -321,6 +321,7 @@ files:
 - lib/lutaml/json/adapter/standard_adapter.rb
 - lib/lutaml/json/adapter/transform.rb
 - lib/lutaml/json/format.rb
+- lib/lutaml/json/generator_options.rb
 - lib/lutaml/json/schema.rb
 - lib/lutaml/json/schema/json_schema.rb
 - lib/lutaml/json/type/serializers.rb
@@ -1638,6 +1639,7 @@ files:
 - spec/lutaml/integration/edge_cases_spec.rb
 - spec/lutaml/integration/multi_format_spec.rb
 - spec/lutaml/integration/round_trip_spec.rb
+- spec/lutaml/json/adapter/standard_adapter_spec.rb
 - spec/lutaml/jsonld/adapter_spec.rb
 - spec/lutaml/key_value/transformation/collection_serializer_spec.rb
 - spec/lutaml/key_value/transformation/rule_compiler_spec.rb
@@ -1657,6 +1659,7 @@ files:
 - spec/lutaml/model/collection_index_spec.rb
 - spec/lutaml/model/collection_mutation_spec.rb
 - spec/lutaml/model/collection_spec.rb
+- spec/lutaml/model/collection_state_nesting_spec.rb
 - spec/lutaml/model/collection_validation_spec.rb
 - spec/lutaml/model/comparable_model_spec.rb
 - spec/lutaml/model/compiled_rule_spec.rb
@@ -1677,6 +1680,7 @@ files:
 - spec/lutaml/model/enum_spec.rb
 - spec/lutaml/model/except_spec.rb
 - spec/lutaml/model/finalization_cache_spec.rb
+- spec/lutaml/model/generator_defaults_spec.rb
 - spec/lutaml/model/global_context_spec.rb
 - spec/lutaml/model/global_register_spec.rb
 - spec/lutaml/model/group_spec.rb
@@ -1686,6 +1690,7 @@ files:
 - spec/lutaml/model/inheritance_spec.rb
 - spec/lutaml/model/json_adapter_spec.rb
 - spec/lutaml/model/json_spec.rb
+- spec/lutaml/model/json_state_nesting_spec.rb
 - spec/lutaml/model/jsonl/standard_adapter_spec.rb
 - spec/lutaml/model/jsonl_spec.rb
 - spec/lutaml/model/key_value_data_model/key_value_element_spec.rb
@@ -1916,6 +1921,7 @@ files:
 - spec/lutaml/xml/schema/xsd/xsd_spec.rb
 - spec/lutaml/xml/schema_primer_spec.rb
 - spec/lutaml/xml/serializable_namespace_spec.rb
+- spec/lutaml/xml/shared_element_rules_spec.rb
 - spec/lutaml/xml/transformation/custom_method_wrapper_spec.rb
 - spec/lutaml/xml/transformation_spec.rb
 - spec/lutaml/xml/type_namespace/collector_spec.rb