lutaml-model 0.8.17 → 0.8.19

data/README.adoc

@@ -303,6 +303,42 @@ gem install lutaml-model
 
 Lutaml::Model includes a command line interface (CLI) that provides useful tools for working with your data models. The CLI is available through the `lutaml-model` command after installation.
 
+== Opal (JavaScript) support
+
+Lutaml::Model runs under
+https://opalrb.com/[Opal] (Ruby compiled to JavaScript), which
+powers the
+https://www.npmjs.com/package/@lutaml/lutaml-model[`@lutaml/lutaml-model`]
+npm package. Two pure-Ruby XML adapters ship under Opal:
+
+* **Oga** (default) — compiled from the vendored `opal-oga` fork,
+  which provides a pure-Ruby lexer.
+* **REXML** (opt-in) — compiled from the bundled stdlib gem, with
+  moxml's `lib/compat/opal/rexml/*` shadows patching the parts Opal
+  can't follow natively.
+
+Nokogiri and Ox are C extensions and are not available under Opal.
+
+[source,ruby]
+----
+# Default (Oga)
+Lutaml::Model::Config.xml_adapter_type = :oga
+
+# Opt-in to REXML
+Lutaml::Model::Config.xml_adapter_type = :rexml
+----
+
+The Opal smoke specs in `spec/lutaml/xml/opal_xml_spec.rb` run a
+shared XML round-trip contract against BOTH adapters so a regression
+in either is caught at CI time (`bundle exec rake spec:opal`).
+
+The npm package `@lutaml/lutaml-model` is rebuilt automatically by
+the `lutaml-model-js` repo on every push to this repo's `main` branch
+(publishes under the `next` dist-tag) and on every stable gem release
+(publishes under `latest`). See
+https://github.com/lutaml/lutaml-model-js[`lutaml-model-js`] for
+details.
+
 === Compare Command
 
 The `compare` command allows you to compare two data files of different formats using your Lutaml::Model classes. This is particularly useful for:
@@ -2657,6 +2693,112 @@ references:
 
 
 
+=== Union attributes
+
+==== General
+
+A union attribute accepts a value conforming to *one of several declared
+types* -- the functional equivalent of `xsd:union`. Declare the member types
+as a bare array in the type position, in priority order:
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :firing_temperature, [TemperatureWithUnit, Temperature, :string]
+
+  xml do
+    root "ceramic"
+    map_element "FiringTemperature", to: :firing_temperature
+  end
+
+  key_value do
+    map "firing_temperature", to: :firing_temperature
+  end
+end
+----
+
+Members may be model classes (`Lutaml::Model::Serializable`) or one of the
+supported scalar value types: `:string`, `:integer`, `:float`, `:decimal`,
+`:boolean`. Other value types (e.g. `:date`, `:date_time`, `:time`, `:symbol`,
+`:uri`) and option hashes such as `{ ref: [...] }` are not supported as union
+members and are rejected at definition time — see Limitations.
+
+==== Semantics
+
+Resolution follows `xsd:union`: the value is matched against the members in
+*declared order*, and the *first member it conforms to wins*. A value is valid
+if it conforms to *at least one* member -- there is no "exactly one" rule.
+
+Conformance is by lexical space for scalars and by key coverage for models:
+
+* A scalar string conforms to `:integer` only if it is an integer literal
+  (`"42"`), to `:float` only if it parses as a finite number, and to
+  `:boolean` only for `true`/`false`. So `[:integer, :string]` resolves `"42"`
+  to the integer `42` but `"hello"` to the string `"hello"`.
+* A structured value conforms to a model member when its keys (hash keys, or
+  XML child-element and attribute names) are covered by that member's mapped
+  fields.
+
+A universal catch-all (`:string`/`String`) must be the *last* member, so
+earlier scalar members stay reachable. This is enforced at definition time.
+
+==== No-match handling
+
+A value that matches no member becomes `nil`, exactly like any other failed
+cast in the library. Use `required: true` for strictness -- a no-match then
+surfaces the standard `RequiredAttributeMissingError` during validation:
+
+[source,ruby]
+----
+class Reading < Lutaml::Model::Serializable
+  attribute :value, [:integer, :float], required: true
+  key_value { map "value", to: :value }
+end
+
+Reading.new(value: "not a number").value      # => nil
+Reading.new(value: "not a number").validate!   # raises (RequiredAttributeMissingError)
+----
+
+There is no `strict:` flag; strictness uses the existing `required:` mechanism.
+
+==== Serialization
+
+Serialization is stateless and driven by the value's own class, so a member
+built in plain Ruby serializes identically to a deserialized one. The same
+element/key name is used for every member; XML distinguishes members by shape
+(text-only for scalars, child elements/attributes for models):
+
+[source,xml]
+----
+<FiringTemperature>Very Hot</FiringTemperature>
+<FiringTemperature><number>1300</number><unit>C</unit></FiringTemperature>
+----
+
+==== Collections
+
+A `collection: true` union resolves each element independently, mixing model
+and scalar members in one collection.
+
+==== Limitations
+
+* JSON Schema export emits `anyOf`. XSD and RelaxNG export raise
+  `UnionSchemaUnsupportedError` -- a union of structured members has no faithful
+  representation in those schema languages.
+* `union` cannot be combined with `polymorphic`, `raw`, `with`, or
+  `child_mappings` (rejected at definition time).
+* Differently-named or namespaced XML members are not supported; members share
+  one element name and are distinguished by shape and key coverage.
+* Scalar members are limited to `:string`, `:integer`, `:float`, `:decimal`,
+  `:boolean` (plus any `Serializable` model). Other value types are rejected at
+  definition time because the stateless, `value.class`-driven serialization
+  cannot recover them faithfully — e.g. `Type::Date.cast` can yield a `DateTime`
+  (so `:date`/`:date_time` are indistinguishable), `:time` and
+  `:time_without_date` share a Ruby `Time` class, and `:hash` is ambiguous with
+  model members for structured input.
+* Reference (`{ ref: [...] }`) or other option-hash members are not supported.
+
+
+
 === Collection attributes
 
 Define attributes as collections (arrays or hashes) to store multiple values
@@ -16444,6 +16586,7 @@ models. This allows you to create models from existing schema definitions.
 Currently, the following schema formats are supported:
 
 * XSD (https://w3.org/TR/xmlschema-1/[XML Schema Definition Language])
+* RELAX NG (https://relaxng.org/[RELAX NG], see <<rng-schema-compilation>>)
 * JSON/YAML Schema
 
 Please refer to link:docs/schema_import.adoc[Schema Import] for details
@@ -17332,6 +17475,130 @@ end
 For a complete architecture overview and migration guide from Register to
 GlobalContext, see link:docs/architecture.md[Architecture Documentation].
 
+[[rng-schema-compilation]]
+== RELAX NG Schema Compilation
+
+Lutaml::Model provides functionality to compile RELAX NG (RNG) schemas into
+Ruby model classes, analogous to <<schema-import,XSD schema import>>.
+
+=== Prerequisite: the `rng` gem
+
+Unlike XSD support, RNG schema parsing is provided by an external gem.
+Lutaml::Model itself does not depend on it -- it is only loaded when
+`Schema.from_relaxng` is actually invoked.
+
+To use `Schema.from_relaxng`, add the https://github.com/lutaml/rng[rng] gem to
+your `Gemfile`:
+
+[source,ruby]
+----
+gem "rng"
+----
+
+Then require it in your application:
+
+[source,ruby]
+----
+require "lutaml/model"
+require "rng"   # provides Rng::Grammar, needed by Schema.from_relaxng
+----
+
+Calling `Schema.from_relaxng` without the rng gem loaded raises:
+
+----
+RNG schema compilation requires the rng gem. Add `gem "rng"` to your Gemfile.
+----
+
+=== Basic usage
+
+[source,ruby]
+----
+sources = Lutaml::Model::Schema.from_relaxng(rng_content)
+# => { "AddressBook" => "...", "Card" => "...", ... }
+----
+
+By default, `from_relaxng` returns a Hash mapping class name to generated Ruby
+source. The `options` hash accepts the same keys as `from_xml`:
+
+`output_dir`::: The directory where the model files will be saved. If not
+provided, a default directory named `rng_models_<timestamp>` is created.
++
+[example]
+`"path/to/directory"`
+
+`create_files`::: A `boolean` argument (`false` by default) to create files directly in the specified directory as defined by the `output_dir` option.
++
+[example]
+`create_files: (true | false)`
+
+`load_classes`::: A `boolean` argument (`false` by default) to load generated classes before returning them.
++
+[example]
+`load_classes: (true | false)`
+
+`module_namespace`::: The Ruby module name that wraps generated classes (e.g.
+`"MyModels"`). If omitted, no wrapping module is generated.
++
+[example]
+`module_namespace: "MyModels"`
+
+NOTE: If both `create_files` and `load_classes` are provided, the `create_files`
+argument will take priority and generate files without loading them!
+
+[example]
+.Using `Lutaml::Model::Schema#from_relaxng` to convert an RNG schema to model files
+====
+[source,ruby]
+----
+options = {
+  # These are all optional:
+  output_dir: "lib/my_models",
+  module_namespace: "MyModels",
+  create_files: true, # Default: false
+  # OR
+  load_classes: true, # Default: false
+}
+
+Lutaml::Model::Schema.from_relaxng(rng_content, options: options)
+----
+====
+
+You could also directly load the generated Ruby files into your application by
+requiring the generated registry.
+
+[example]
+.Using the generated Ruby files in your application
+====
+[source,ruby]
+----
+Lutaml::Model::Schema.from_relaxng(
+  rng_content,
+  options: { output_dir: "lib/my_models", create_files: true, module_namespace: "MyModels" }
+)
+require "lib/my_models/mymodels_registry"
+MyModels.register_all
+
+MyModels::AddressBook.from_xml(xml_content)
+----
+====
+
+=== Supported RNG constructs
+
+* `<grammar>`, `<start>`, `<define>`
+* `<element>` (nested and ref-targeted)
+* `<attribute>` -> `map_attribute`
+* `<ref>` -- resolves wrapping defines to typed attributes; resolves
+  fragment defines (multi-element or attribute-group) to `import_model`
+* `<optional>`, `<zeroOrMore>`, `<oneOrMore>`, `<group>`, `<choice>`
+* `<text/>`, `<data type="..."/>` (string/integer/boolean/float/decimal/date/dateTime/time)
+* `<empty/>`, `<mixed>`
+
+=== Round-trip with RELAX NG generation
+
+`Schema.from_relaxng` is round-trip-compatible with
+`Lutaml::Xml::Schema::RelaxngSchema.generate`: taking a model, generating
+RNG from it, and compiling the RNG back yields equivalent class source.
+
 [[document-validation-framework]]
 == Document Validation Framework
 

data/Rakefile

@@ -1,14 +1,176 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+# vendor:prepare must be runnable before `bundle install` (CI runs it
+# first so the path-source oga/ruby-ll forks' gitignored lexer/parser
+# outputs exist before their extconf.rb runs). Guard the rspec/opal
+# requires so the file loads with only `rake` + `bundler` available.
+begin
+  require "rspec/core/rake_task"
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+end
 
-require "rubocop/rake_task"
+begin
+  require "opal/rspec/rake_task"
 
-RuboCop::RakeTask.new
+  # Opal-compatible overrides need to be on Opal's global load path so
+  # the compiler can follow `require "lutaml_model_boot"` etc.
+  # moxml ships its own compat files (`lib/compat/opal/`) inside the gem;
+  # we add moxml's gem dir to Opal's load path so we can reuse them.
+  # moxml's lib root is also added so `require "moxml"` resolves.
+  #
+  # The REXML gem is a bundled Ruby stdlib gem (pure Ruby). moxml's
+  # lib/compat/opal/rexml/* shadows patch its namespace/text/source/etc.
+  # for Opal. For `require "rexml/document"` and friends to resolve, the
+  # gem's lib dir must be on Opal's load path (mirrors what moxml does).
+  if defined?(Opal)
+    Opal.append_path File.expand_path("lib/compat/opal", __dir__)
+
+    moxml_gem_dir = Gem::Specification.find_by_name("moxml")&.gem_dir
+    if moxml_gem_dir
+      Opal.append_path File.join(moxml_gem_dir, "lib")
+      Opal.append_path File.join(moxml_gem_dir, "lib/compat/opal")
+    end
+
+    rexml_lib = $LOAD_PATH.find do |p|
+      File.exist?(File.join(p, "rexml", "document.rb"))
+    end
+    Opal.append_path rexml_lib if rexml_lib
+
+    # The Opal-compatible oga and ruby-ll forks (vendored as submodules)
+    # expose pure-Ruby implementations under ext/pureruby/. Their top-level
+    # lib/oga.rb and lib/ll/setup.rb conditionally require them when
+    # RUBY_PLATFORM == 'opal'. Both lib/ and ext/pureruby/ must be on
+    # Opal's load path so the conditional resolves correctly.
+    %w[opal-oga opal-ruby-ll].each do |fork_name|
+      fork_path = File.expand_path("vendor/#{fork_name}", __dir__)
+      Opal.append_path File.join(fork_path, "lib")
+      Opal.append_path File.join(fork_path, "ext/pureruby")
+    end
+  end
+rescue LoadError
+  # Opal not available or incompatible with current Ruby version
+end
+
+begin
+  require "rubocop/rake_task"
+  RuboCop::RakeTask.new
+rescue LoadError
+end
 
 Dir.glob("lib/tasks/**/*.rake").each { |r| load r }
 
+# Regenerate the ragel / ruby-ll outputs that the Opal-compatible forks
+# (vendored as submodules under vendor/) gitignore. The forks ship the
+# grammar sources (.rl / .rll) but not the generated .rb / .c, since
+# those are large and version-controllable upstream. Both ragel and
+# ruby-ll must be on PATH; the upstream ruby-ll gem is sufficient for
+# generation (the fork is only needed at runtime).
+namespace :vendor do
+  desc "Generate ragel / ruby-ll outputs in vendored opal-oga and opal-ruby-ll"
+  task :prepare do
+    require "fileutils"
+
+    oga = File.expand_path("vendor/opal-oga", __dir__)
+    ruby_ll = File.expand_path("vendor/opal-ruby-ll", __dir__)
+
+    generators = [
+      # oga: ruby-ll grammar -> Ruby parser
+      ["ruby-ll #{oga}/lib/oga/xml/parser.rll -o #{oga}/lib/oga/xml/parser.rb",
+       "#{oga}/lib/oga/xml/parser.rb",
+       "#{oga}/lib/oga/xml/parser.rll"],
+      ["ruby-ll #{oga}/lib/oga/xpath/parser.rll -o #{oga}/lib/oga/xpath/parser.rb",
+       "#{oga}/lib/oga/xpath/parser.rb",
+       "#{oga}/lib/oga/xpath/parser.rll"],
+      ["ruby-ll #{oga}/lib/oga/css/parser.rll -o #{oga}/lib/oga/css/parser.rb",
+       "#{oga}/lib/oga/css/parser.rb",
+       "#{oga}/lib/oga/css/parser.rll"],
+      # oga: ragel Ruby lexer
+      ["ragel -R -F1 #{oga}/lib/oga/xpath/lexer.rl -o #{oga}/lib/oga/xpath/lexer.rb",
+       "#{oga}/lib/oga/xpath/lexer.rb",
+       "#{oga}/lib/oga/xpath/lexer.rl"],
+      ["ragel -R -F1 #{oga}/lib/oga/css/lexer.rl -o #{oga}/lib/oga/css/lexer.rb",
+       "#{oga}/lib/oga/css/lexer.rb",
+       "#{oga}/lib/oga/css/lexer.rl"],
+      # oga: ragel C lexer for liboga
+      ["ragel -C -I #{oga}/ext/ragel -G2 #{oga}/ext/c/lexer.rl -o #{oga}/ext/c/lexer.c",
+       "#{oga}/ext/c/lexer.c",
+       "#{oga}/ext/c/lexer.rl"],
+      # ruby-ll: ruby-ll grammar -> Ruby parser
+      ["ruby-ll #{ruby_ll}/lib/ll/parser.rll -o #{ruby_ll}/lib/ll/parser.rb --no-requires",
+       "#{ruby_ll}/lib/ll/parser.rb",
+       "#{ruby_ll}/lib/ll/parser.rll"],
+    ]
+
+    generators.each do |cmd, output, source|
+      if File.exist?(output) && File.mtime(output) >= File.mtime(source)
+        next
+      end
+
+      FileUtils.mkdir_p(File.dirname(output))
+      sh cmd
+    end
+  end
+
+  # Bundler does not reliably compile native extensions for path-source
+  # gems. Build liboga/libll explicitly so `require "oga"` resolves.
+  desc "Compile liboga / libll native extensions for vendored forks"
+  task :compile do
+    require "fileutils"
+    require "rbconfig"
+
+    dlext = RbConfig::CONFIG["DLEXT"]
+
+    {
+      "vendor/opal-ruby-ll" => "libll",
+      "vendor/opal-oga" => "liboga",
+    }.each do |fork_path, ext_name|
+      abs_fork = File.expand_path(fork_path, __dir__)
+      lib_bundle = File.join(abs_fork, "lib", "#{ext_name}.#{dlext}")
+      ext_dir = File.join(abs_fork, "ext", "c")
+      extconf = File.join(ext_dir, "extconf.rb")
+      lib_dir = File.join(abs_fork, "lib")
+      next if File.exist?(lib_bundle)
+
+      Dir.chdir(ext_dir) do
+        sh "ruby #{extconf}"
+        sh "make"
+        FileUtils.cp("#{ext_name}.#{dlext}", lib_dir)
+      end
+    end
+  end
+end
+
+if defined?(RSpec)
+  namespace :spec do
+    if defined?(Opal::RSpec::RakeTask)
+      desc "Run Opal (JavaScript) tests"
+      Opal::RSpec::RakeTask.new(:opal) do |server, runner|
+        server.append_path "lib"
+        server.append_path "spec"
+
+        runner.default_path = "spec"
+        # Load order matters:
+        #   rexml_compat      — moxml stdlib shim (String/Encoding/StringIO) required by Oga
+        #   yaml_compat       — adds YAML.safe_load / YAML.dump on top of Opal's nodejs/yaml
+        #   oga, ll/setup     — forks' Opal-aware conditionals select pure-Ruby lexer
+        #   moxml_boot        — eager-loads Moxml::* (lutaml-model's copy, skips broken REXML paths in moxml 0.1.25)
+        #   lutaml_model_boot — eager-loads Lutaml::* (Opal ignores autoload)
+        #   spec_helper, support/opal — test infrastructure
+        runner.requires = %w[rexml_compat yaml_compat
+                             oga ll/setup
+                             moxml_boot
+                             lutaml_model_boot
+                             spec_helper support/opal]
+        runner.files = Dir.glob("spec/lutaml/**/opal*_spec.rb")
+      end
+
+      desc "Alias for spec:opal that also runs vendor:prepare"
+      task opal: "vendor:prepare"
+    end
+  end
+end
+
 task default: %i[spec rubocop]

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/schema-import.adoc

@@ -59,6 +59,8 @@ create corresponding LutaML models.
 Currently, the following schema formats are supported for import:
 
 * XSD (https://w3.org/TR/xmlschema-1/[XML Schema Definition Language])
+* RELAX NG XML syntax (RNG)
+* RELAX NG compact syntax (RNC)
 * JSON Schema (https://json-schema.org/[JSON Schema specification])
 * YAML Schema (YAML-based JSON Schema definitions)
 
@@ -235,6 +237,46 @@ require_relative 'path/to/directory/*.rb'
 
 For detailed XSD schema parsing (inspecting and manipulating XSD schemas as Ruby objects, including round-tripping), see the link:./_references/xsd-schema-parsing.adoc[XSD Schema Parsing Reference].
 
+=== RELAX NG import
+
+Lutaml::Model supports importing RELAX NG XML syntax (`*.rng`) and RELAX NG
+compact syntax (`*.rnc`) schemas into Ruby model classes.
+
+RNC import is implemented as a thin adapter over RNG import:
+
+[source]
+----
+RNC source -> Rng::Grammar -> RngCompiler -> Lutaml::Model classes
+----
+
+The `rng` gem provides RNC/RNG parsing and must be available before using
+these APIs.
+
+[source,ruby]
+----
+require "lutaml/xml"
+require "rng"
+
+rng_sources = Lutaml::Model::Schema.from_relaxng(rng_content)
+rnc_sources = Lutaml::Model::Schema.from_rnc(rnc_content)
+----
+
+Both methods return a hash mapping generated class names to Ruby source by
+default. They also support the same file-generation options as XSD import:
+
+[source,ruby]
+----
+Lutaml::Model::Schema.from_rnc(
+  File.read("reference-docs/v3.rnc"),
+  location: "reference-docs/v3.rnc",
+  output_dir: "lib/rfcxml",
+  create_files: true,
+  module_namespace: "RfcXml",
+)
+----
+
+When an RNC schema contains local `include "..."` directives, pass `location:`
+as either the source file path or the directory used to resolve those includes.
 
 === JSON Schema import
 

data/docs/_guides/xml-mapping.adoc

@@ -1172,6 +1172,27 @@ class MultiFragment < Lutaml::Model::Serializable
   end
 end
 ----
+
+`raw: :element` also works on `mixed_content` and `ordered` parents. The
+captured string is emitted verbatim regardless of which applier dispatches the
+rule. This matters for round-trip serialization: when a model is parsed from
+XML, `element_order` is populated and the `OrderedApplier` path takes over --
+without the `raw: :element` short-circuit, each captured fragment (which already
+contains its own wrapper tag) would be wrapped again, producing
+`<fragment><fragment>...</fragment></fragment>`.
+
+[source,ruby]
+----
+class WordParagraph < Lutaml::Model::Serializable
+  attribute :runs, :string, collection: true
+
+  xml do
+    element "p"
+    mixed_content
+    map_element "oMath", to: :runs, raw: :element
+  end
+end
+----
 ====
 
 ===== `raw: :content` on `map_element` -- inner content capture