lutaml-model 0.8.22 → 0.8.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a30fcd552dca587769736a81de33b66909c592cbc5ed40f696d34fbaf7de887f
-  data.tar.gz: b15506fd1398cad525dcac0a624166cdc23dedf7faa3e282b1aae10c583b405a
+  metadata.gz: c8aca94b467fe681429ee9863355555d3aa003d9deda8543a74fd1424087bcc8
+  data.tar.gz: 02db8dceef19fc7ef7abd3a54f0936e00ef162a1ee6477191a8b1d3477ba7860
 SHA512:
-  metadata.gz: 061ea9253cc7e425f9591e5f57407935eb6b52b1ee69fc5b289b672a0109f8aa3850097d0dd3971613b6010c5e8d83b5425e3447bebe0ae6724916fbdc7a3173
-  data.tar.gz: 9280bc8adfdeaa2e6167c57379d0d40a7c8c27a4dffb420c8f8b6468b893df8ae72207d5fddef2885d4954ba4c45918a1f9cd3746ef2194aed3b09bae46b19f9
+  metadata.gz: 4da87513ed839ba070c32b28de27411ffe12ccc92f879a0dbe433aad85ea3a32a76759b36112958a131b09a747b1618c0ff8a95e92238aca40f45b736dd46950
+  data.tar.gz: ff488be2b79ef92c3017d63ee0a9bf4ac3b183549be5b17a59efcb42ea31ae00cacb2b63995f9b69fbe3628af9bd65f30dfedb2fb5d2722fe15189c7e964a93b

data/.github/workflows/performance.yml

@@ -16,7 +16,7 @@ permissions:
 jobs:
   performance:
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 30
     steps:
       - uses: actions/checkout@v6
         with:

data/Gemfile

@@ -19,6 +19,7 @@ gem "benchmark-ips"
 gem "bigdecimal"
 gem "canon" # , path: "../canon"
 gem "json-ld"
+gem "leptris"
 gem "liquid", "~> 5"
 gem "multi_json"
 gem "nokogiri"
@@ -26,8 +27,11 @@ gem "oj"
 gem "openssl", "~> 3.0"
 gem "ox"
 gem "rake"
+# yeptris ships prebuilt platform gems for linux/darwin only; a source
+# build is not wired for windows runners.
 gem "rdf-turtle"
 gem "rexml"
+gem "yeptris" unless Gem.win_platform?
 # TODO: revert rng branch to main when lutaml/rng#32 is merged
 gem "rng", git: "https://github.com/lutaml/rng", branch: "main"
 gem "rspec"
@@ -35,6 +39,8 @@ gem "rubocop"
 gem "rubocop-performance", require: false
 gem "rubocop-rake", require: false
 gem "rubocop-rspec", require: false
+# teptris ships prebuilt gems for every platform (incl. mingw-ucrt)
+gem "teptris"
 gem "tomlib"
 gem "toml-rb"
 

data/README.adoc

@@ -16223,7 +16223,7 @@ Adapters are auto-detected on first use. The defaults when gems are available:
 * YAML: `:standard` (alias: `:standard_yaml`)
 * JSON: `:standard` (alias: `:standard_json`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 
 ==== Configure adapters through symbol choices
@@ -16246,7 +16246,7 @@ Lutaml::Model::Config.configure do |config|
   config.hash_adapter = :standard
   config.yaml_adapter = :standard
   config.json_adapter = :standard # can be one of [:standard, :multi_json, :oj]
-  config.toml_adapter = :toml_rb # can be one of [:toml_rb, :tomlib]
+  config.toml_adapter = :toml_rb # can be one of [:teptris, :toml_rb, :tomlib]
 end
 ----
 
@@ -16388,22 +16388,29 @@ end
 
 Lutaml::Model supports the following TOML adapters:
 
+Teptris::
+(default when the `teptris` gem is in the bundle — every platform)
+The native TOML engine (libteptris via FFI). Value semantics mirror
+tomlib: offset and local datetimes become `Time`, dates become `Date`,
+local times stay `String`.
+Requires the `teptris` gem.
+
 Toml-rb::
-(default on Windows)
+(default on Windows without teptris)
 A TOML parser and serializer for Ruby that is compatible with the TOML v1.0.0
 specification.
 Requires the `toml-rb` gem.
 
 Tomlib::
-(default on non-Windows platforms)
+(default on non-Windows platforms without teptris)
 Toml-rb fork that is compatible with the TOML v1.0.0 specification, but with
 additional features.
 Requires the `tomlib` gem.
 
 IMPORTANT: The Tomlib adapter is not available on Windows due to segmentation
-fault issues. On Windows, the `toml-rb` adapter is used automatically as the
-default. If you explicitly configure `tomlib` on Windows, a
-`ConfigurationError` will be raised.
+fault issues. On Windows, the `teptris` adapter (when bundled) or the
+`toml-rb` adapter is used automatically as the default. If you explicitly
+configure `tomlib` on Windows, a `ConfigurationError` will be raised.
 
 
 .Using a TOML adapter
@@ -16412,6 +16419,8 @@ default. If you explicitly configure `tomlib` on Windows, a
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
+  config.toml_adapter = :teptris
+  # or
   config.toml_adapter = :toml_rb
   # or (not available on Windows)
   config.toml_adapter = :tomlib

data/docs/_guides/index.adoc

@@ -22,6 +22,10 @@ Task-oriented guides for accomplishing specific goals with Lutaml::Model.
 * link:../keyvalue-serialization[Key-Value Serialization] - JSON/YAML/TOML/Hash
 * link:../collection-serialization[Collection Serialization] - JSONL and YAML Stream
 
+== Performance
+
+* link:../native-engines[Native engines (leptris / yeptris / teptris)] - Drop-in XML/YAML/JSON/TOML engine upgrades via bundle opt-in
+
 == Linked Data serialization
 
 * link:../rdf-serialization[Unified RDF Serialization] - One `rdf` block for both JSON-LD and Turtle

data/docs/_guides/native-engines.adoc

@@ -0,0 +1,61 @@
+= Native engines (leptris / yeptris / teptris)
+
+By default, `lutaml-model` serializes through the same engines every Ruby
+install already has: Nokogiri (via moxml) for XML, Psych for YAML, the
+`json` gem for JSON.
+
+The leptris family of native engines is a drop-in performance upgrade:
+
+* **leptris** — the XML engine moxml drives. When the `leptris` gem is in
+  your bundle, moxml prefers it over Nokogiri for parsing and
+  serialization.
+* **yeptris** — the YAML/JSON engine. When the `yeptris` gem is in your
+  bundle, lutaml-model's YAML and JSON adapters resolve to the yeptris
+  engine.
+* **teptris** — the TOML engine. When the `teptris` gem is in your
+  bundle it becomes the TOML default on every platform (0.2.12+ parses
+  ~3x and dumps ~8x faster than tomlib, and the Windows mingw-ucrt
+  prebuilts are back), giving Windows native TOML and retiring the
+  tomlib-segfault workaround (previously pure-Ruby toml-rb only).
+
+Opting in is purely a bundle decision — no code changes, no gemspec
+requirements:
+
+[source,sh]
+----
+bundle add leptris yeptris teptris
+----
+
+leptris and yeptris ship prebuilt platform gems for Linux and macOS
+(yeptris has no Windows prebuilts). teptris ships prebuilt gems for
+every platform, including Windows. When a gem is absent, lutaml-model
+automatically falls back to the standard engine for that format.
+
+== Selecting adapters explicitly
+
+The engines register as ordinary adapter types, so explicit selection and
+the availability error messages work as usual:
+
+[source,ruby]
+----
+Lutaml::Model::Config.xml_adapter_type = :leptris
+Lutaml::Model::Config.yaml_adapter_type = :yeptris
+Lutaml::Model::Config.json_adapter_type = :yeptris
+Lutaml::Model::Config.toml_adapter_type = :teptris
+----
+
+== Semantics notes
+
+* **YAML**: the yeptris adapter uses the engine's `compat_11` schema, so
+  implicit typing matches Psych (parity-verified across the scalar
+  battery: dates, timestamps, octal, sexagesimal, `yes`/`no`, `.inf`).
+  Two deliberate differences: anchors and aliases always resolve, and a
+  tagged value without a core type materializes as plain data instead of
+  raising `Psych::DisallowedClass`.
+* **JSON**: `yeptris` parsing targets exact `JSON.parse` semantics;
+  generation stays on the `json` gem.
+* **TOML**: the teptris adapter mirrors tomlib value semantics — offset
+  and local datetimes become `Time`, dates become `Date`, local times
+  stay `String`. Parse failures raise `Teptris::ParseError` with line
+  and column, wrapped as `InvalidFormatError` like the other TOML
+  adapters.

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/docs/_pages/configuration.adoc

@@ -23,7 +23,7 @@ The auto-detection order for each format:
 |===
 | Format | Detection order
 | XML | `:nokogiri` → `:ox` → `:oga` → `:rexml`
-| TOML | `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+| TOML | `:teptris` → `:tomlib` → `:toml_rb` (Windows: `:teptris` → `:toml_rb`)
 | JSON | `:standard` (always available)
 | YAML | `:standard` (always available)
 | Hash | `:standard` (always available)
@@ -109,14 +109,17 @@ When an adapter is needed for a format, `AdapterResolver` follows this chain:
 |===
 | Adapter | Description
 
+| `:teptris` (default when bundled)
+| Native engine (libteptris via FFI), all platforms including Windows. tomlib-compatible value semantics.
+
 | `:tomlib` (default on non-Windows)
 | Enhanced fork. Better performance on non-Windows platforms.
 
-| `:toml_rb` (default on Windows)
-| Pure Ruby. TOML v1.0.0 compatible. Required on Windows.
+| `:toml_rb` (default on Windows without teptris)
+| Pure Ruby. TOML v1.0.0 compatible.
 |===
 
-NOTE: The `:tomlib` adapter is not available on Windows due to segmentation fault issues. On Windows, `:toml_rb` is automatically used as the default.
+NOTE: The `:tomlib` adapter is not available on Windows due to segmentation fault issues. On Windows, `:teptris` (when bundled) or `:toml_rb` is used as the default.
 
 == Per-operation adapter override
 
@@ -226,7 +229,7 @@ If not explicitly configured, Lutaml::Model auto-detects on first use:
 * JSON: `:standard` (alias: `:standard_json`)
 * YAML: `:standard` (alias: `:standard_yaml`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 == When to configure
 
@@ -272,8 +275,9 @@ end
 
 === Choose TOML adapter based on
 
-* **Tomlib**: Most projects on non-Windows (better performance)
-* **TomlRb**: Windows platforms (required due to tomlib incompatibility)
+* **Teptris**: Bundled native engine — ~3x faster parse, ~8x faster dump than tomlib, every platform
+* **Tomlib**: Non-Windows projects without teptris (better performance)
+* **TomlRb**: Windows platforms without teptris (required due to tomlib incompatibility)
 
 == Opal runtime compatibility
 

data/docs/_pages/serialization_adapters.adoc

@@ -48,7 +48,7 @@ more information.
 Adapters are resolved lazily on first use. If no adapter is explicitly configured, `AdapterResolver` probes for available gems in a preferred order:
 
 * **XML**: `:nokogiri` → `:ox` → `:oga` → `:rexml`
-* **TOML**: `:tomlib` → `:toml_rb` (Windows: `:toml_rb` only)
+* **TOML**: `:teptris` → `:tomlib` → `:toml_rb` (Windows: `:teptris` → `:toml_rb`)
 * **JSON/YAML/Hash**: `:standard` (always available)
 
 The detection result is cached after the first probe, so it only runs once per format.
@@ -84,7 +84,7 @@ There is a default configuration for adapters for commonly used formats:
 * YAML: `:standard` (alias: `:standard_yaml`)
 * JSON: `:standard` (alias: `:standard_json`)
 * Hash: `:standard` (alias: `:standard_hash`)
-* TOML: `:tomlib` on non-Windows, `:toml_rb` on Windows
+* TOML: `:teptris` if available, else `:tomlib` on non-Windows, `:toml_rb` on Windows
 
 
 ==== Configure adapters through symbol choices
@@ -107,7 +107,7 @@ Lutaml::Model::Config.configure do |config|
   config.hash_adapter = :standard
   config.yaml_adapter = :standard
   config.json_adapter = :standard # can be one of [:standard, :multi_json, :oj]
-  config.toml_adapter = :toml_rb # can be one of [:toml_rb, :tomlib] (tomlib not available on Windows)
+  config.toml_adapter = :toml_rb # can be one of [:teptris, :toml_rb, :tomlib] (tomlib not available on Windows)
 end
 ----
 
@@ -285,8 +285,16 @@ end
 
 Lutaml::Model supports the following TOML adapters:
 
+Teptris::
+(default when the `teptris` gem is in the bundle — every platform)
+The native TOML engine (libteptris via FFI). Value semantics mirror
+tomlib: offset and local datetimes become `Time`, dates become `Date`,
+local times stay `String`. Parse failures raise `Teptris::ParseError`
+with line and column.
+Requires the `teptris` gem.
+
 Tomlib::
-(default on non-Windows)
+(default on non-Windows when teptris is absent)
 Toml-rb fork that is compatible with the TOML v1.0.0 specification, with
 additional features and better performance.
 Requires the `tomlib` gem.
@@ -348,4 +356,5 @@ raised to indicate that the input format is malformed and cannot be parsed.
 
 NOTE: The `:tomlib` TOML adapter is disabled on Windows due to segmentation
 fault issues. Attempting to configure `:tomlib` on Windows will raise an
-`ArgumentError`. Use `:toml_rb` on Windows instead.
+`ArgumentError`. Use `:teptris` (native, all platforms) or `:toml_rb` on
+Windows instead.

data/lib/compat/opal/lutaml_model_boot.rb

@@ -167,6 +167,8 @@ require "lutaml/xml/oga"
 require "lutaml/xml/parse_session"
 require "lutaml/xml/parsed_namespace_declaration"
 require "lutaml/xml/parsed_namespace_set"
+require "lutaml/xml/plan_compiler"
+require "lutaml/xml/plan_hydrator"
 require "lutaml/xml/polymorphic_value_handler"
 require "lutaml/xml/qualified_inheritance_strategy"
 require "lutaml/xml/rexml"

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

@@ -16,6 +16,8 @@ module Lutaml
                 "multi_json gem is not available. Please add 'multi_json' to your Gemfile."
         end
 
+        INTERNAL_LUTAML_KEYS = %i[register adapter _adapter_override].freeze
+
         # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
         def to_json(*args)
           require "multi_json"
@@ -28,7 +30,16 @@ module Lutaml
                                       @attributes
                                     end
 
-          MultiJson.dump(attributes_to_serialize, *args)
+          # LutaML's own threading keys must not reach the backend; the
+          # rest (e.g. :pretty) are meaningful to multi_json. The json
+          # gem 3.x and Oj raise on unknown generator options, unlike
+          # json 2.x which ignored them.
+          dump_args = args.map do |arg|
+            next arg unless arg.is_a?(::Hash)
+
+            arg.except(*INTERNAL_LUTAML_KEYS)
+          end
+          MultiJson.dump(attributes_to_serialize, *dump_args)
         # rubocop:enable Style/ArgumentsForwarding
         rescue LoadError
           raise LoadError,

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/adapter/yeptris_adapter.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "yeptris"
+require_relative "standard_adapter"
+
+module Lutaml
+  module Json
+    module Adapter
+      # JSON parsing over the yeptris engine: Yeptris::JSON.load targets
+      # exact JSON.parse semantics (spec-pinned upstream), with a fused
+      # native materializer when the loaded libyeptris build carries it.
+      # Generation stays on the json gem (the yeptris JSON surface is
+      # load-only), so everything else inherits from the standard adapter.
+      class YeptrisAdapter < StandardAdapter
+        def self.parse(json, _options = {})
+          ::Yeptris::JSON.load(json)
+        end
+      end
+    end
+  end
+end

data/lib/lutaml/json/adapter.rb

@@ -14,6 +14,7 @@ module Lutaml
         self,
         OjAdapter: "#{__dir__}/adapter/oj_adapter",
         MultiJsonAdapter: "#{__dir__}/adapter/multi_json_adapter",
+        YeptrisAdapter: "#{__dir__}/adapter/yeptris_adapter",
       )
     end
   end

data/lib/lutaml/json/format.rb

@@ -52,7 +52,7 @@ Lutaml::Model::FormatRegistry.register(
   transformer: Lutaml::Json::Adapter::Transform,
   key_value: true,
   adapter_options: {
-    available: %i[standard standard_json multi_json oj],
+    available: %i[standard standard_json multi_json oj yeptris],
     default: :standard,
   },
 )

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/multi_json_adapter.rb

@@ -20,6 +20,8 @@ module Lutaml
                   "multi_json gem is not available. Please add 'multi_json' to your Gemfile."
           end
 
+          INTERNAL_LUTAML_KEYS = %i[register adapter _adapter_override].freeze
+
           # rubocop:disable Style/ArgumentsForwarding -- anonymous * requires Ruby 3.2+
           def to_json(*args)
             require "multi_json"
@@ -32,7 +34,20 @@ module Lutaml
                                         @attributes
                                       end
 
-            MultiJson.dump(attributes_to_serialize, *args)
+            # LutaML's own options must not reach the backend: the json
+            # gem 3.x and Oj both raise on unknown generator options
+            # (multi_json's backend choice shifts with the resolved json
+            # version), unlike json 2.x which ignored them.
+            # LutaML's own threading keys must not reach the backend; the
+            # rest (e.g. :pretty) are meaningful to multi_json. The json
+            # gem 3.x and Oj raise on unknown generator options, unlike
+            # json 2.x which ignored them.
+            dump_args = args.map do |arg|
+              next arg unless arg.is_a?(::Hash)
+
+              arg.except(*INTERNAL_LUTAML_KEYS)
+            end
+            MultiJson.dump(attributes_to_serialize, *dump_args)
           # rubocop:enable Style/ArgumentsForwarding
           rescue LoadError
             raise LoadError,

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)