lutaml-model 0.8.16 → 0.8.18

data/docs/_guides/xml-namespace-qualification.adoc

@@ -509,6 +509,148 @@ Parent.new(child: Child.new(value: "test")).to_xml(prefix: true)
 
 All three elements (`parent`, `child`, `value`) use the prefix because all are qualified via `element_form_default: :qualified`.
 
+=== Form Override on Serializable Children
+
+The `form:` option works on attributes of any type — including attributes whose value type is another `Serializable` model, not only simple types like `:string`. This matters when the parent's namespace declares `element_form_default :unqualified` (the W3C default) and you need a specific nested model element to be qualified anyway.
+
+.Worked example: form: :qualified on a Serializable child
+[example]
+====
+[source,ruby]
+----
+NS = Class.new(Lutaml::Model::XmlNamespace) do
+  uri "https://example.com/ns"
+  prefix_default "ex"
+  element_form_default :unqualified  # W3C default for local elements
+end
+
+class Child < Lutaml::Model::Serializable
+  attribute :label, :string
+  xml do
+    element "child"
+    namespace NS
+    map_element "label", to: :label
+  end
+end
+
+class Parent < Lutaml::Model::Serializable
+  attribute :child, Child
+  xml do
+    element "item"
+    namespace NS
+    map_element "child", to: :child, form: :qualified  # Force prefix
+  end
+end
+
+Parent.new(child: Child.new(label: "x")).to_xml
+----
+
+*Output*:
+[source,xml]
+----
+<item xmlns="https://example.com/ns" xmlns:ex="https://example.com/ns">
+  <ex:child>
+    <label>x</label>
+  </ex:child>
+</item>
+----
+
+The `ex:` prefix on `<child>` is forced by `form: :qualified`, overriding the parent's `:unqualified` schema default. The inner `<label>` remains unprefixed because the `Child` model's own mapping rule for `label` has no `form:` override — see the next section.
+====
+
+=== Form Scope: Per-Rule, Not Transitive
+
+`form:` is a per-mapping-rule override. It does **not** propagate transitively to grandchildren. Each level of the model tree applies its own rule against its own parent's `element_form_default`.
+
+.Worked example: form on parent does not cascade to grandchild
+[example]
+====
+[source,ruby]
+----
+NS = Class.new(Lutaml::Model::XmlNamespace) do
+  uri "https://example.com/ns"
+  prefix_default "ex"
+  element_form_default :unqualified
+end
+
+class Grandchild < Lutaml::Model::Serializable
+  attribute :value, :string
+  xml do
+    element "grandchild"
+    namespace NS
+    map_element "value", to: :value
+  end
+end
+
+class Child < Lutaml::Model::Serializable
+  attribute :inner, Grandchild
+  xml do
+    element "child"
+    namespace NS
+    map_element "grandchild", to: :inner  # NO form: override
+  end
+end
+
+class Parent < Lutaml::Model::Serializable
+  attribute :child, Child
+  xml do
+    element "item"
+    namespace NS
+    map_element "child", to: :child, form: :qualified  # Parent's rule only
+  end
+end
+
+Parent.new(child: Child.new(inner: Grandchild.new(value: "x"))).to_xml
+----
+
+*Output*:
+[source,xml]
+----
+<item xmlns="https://example.com/ns" xmlns:ex="https://example.com/ns">
+  <ex:child>
+    <grandchild>
+      <value>x</value>
+    </grandchild>
+  </ex:child>
+</item>
+----
+
+* `<ex:child>` is qualified because the *Parent* rule has `form: :qualified`.
+* `<grandchild>` is unprefixed because the *Child* rule has no `form:` and the Child's namespace is `:unqualified`.
+* The Parent's `form: :qualified` does **not** cascade.
+====
+
+To qualify every level, either set `form: :qualified` on each mapping rule that needs it, or set `element_form_default :qualified` on the namespace so inheritance handles it.
+
+== Qualification Precedence
+
+When serializing an element, the namespace is resolved by checking the following sources in priority order. The first match wins.
+
+[cols="1,4", options="header"]
+|===
+|Priority |Source
+
+|1 (highest)
+|Type-level namespace: the attribute's value type (a `Type::Value` subclass) declares `xml_namespace`. Wins over everything else.
+
+|2
+|Rule-level namespace: the mapping rule has an explicit `namespace:` option. *However*, if the parent's `element_form_default` is `:unqualified` AND the rule's namespace matches the parent's, the namespace is overridden to blank — W3C unqualified semantics for local elements.
+
+|3
+|`form: :unqualified` on the rule: force the element into no namespace.
+
+|4
+|Parent's `element_form_default :qualified` inheritance: the child inherits the parent's namespace — but only if the child model itself declares a namespace (W3C: `elementFormDefault` applies to locally-declared elements only).
+
+|5
+|`form: :qualified` on the rule: inherit the parent's namespace.
+
+|6 (lowest)
+|No namespace.
+|===
+
+This ladder is implemented in `Lutaml::Xml::Transformation::ElementBuilder#determine_element_namespace`. The `ElementFormOptionRule` decision rule reads the propagated `form` value during the planning phase and forces prefix (`:qualified`) or default (`:unqualified`) format accordingly.
+
 == Type Namespaces
 
 Value types can define their own namespaces:

data/docs/_pages/validation.adoc

@@ -72,6 +72,71 @@ The `required: true` option validates that an attribute is present.
 attribute :name, :string, required: true
 ----
 
+=== XML schema validation
+
+The `validate_xml_with` class macro validates the model's generated XML
+against one or more XML Schema (XSD) files during `validate` / `validate!`.
+
+[source,ruby]
+----
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+
+  xml do
+    root "person"
+    map_element "name", to: :name
+  end
+
+  validate_xml_with "schemas/person.xsd"
+end
+
+person = Person.new(name: "Alice")
+person.validate   # => collects Lutaml::Xml::Error::SchemaValidationError
+                  #    instances when the generated XML does not conform
+person.validate!  # => raises Lutaml::Model::ValidationError on nonconformance
+----
+
+The macro accepts one or more schema paths, and repeated calls append to the
+configured list. Subclasses inherit the parent's schema paths parent-first;
+paths added by a subclass do not affect the parent.
+
+[source,ruby]
+----
+validate_xml_with "schemas/base.xsd", "schemas/extensions.xsd"
+----
+
+Raw XML strings can be checked against the same schemas with the explicit
+class-level helpers, for example to reject nonconforming input before
+`from_xml`:
+
+[source,ruby]
+----
+Person.validate_xml(xml_string)   # => array of schema validation errors
+Person.validate_xml!(xml_string)  # => raises Lutaml::Model::ValidationError
+----
+
+NOTE: `to_xml` and `from_xml` never validate implicitly. Call `validate!`
+before serializing, or `validate_xml!` on incoming XML, when enforcement is
+needed — the same explicit contract as every other validation type.
+
+XSD validation uses Nokogiri, which is required lazily on first validation.
+The schemas must be local files declared explicitly; `xsi:schemaLocation`
+in documents is not read and remote schemas are not fetched. Relative paths
+resolve against the file that declares `validate_xml_with`, so a model works
+regardless of the process working directory.
+
+Misconfiguration raises instead of being collected as validation errors:
+
+* a missing schema file raises `Errno::ENOENT`;
+* a malformed XSD raises `Nokogiri::XML::SyntaxError`;
+* a malformed XML string passed to `validate_xml` / `validate_xml!` raises
+  `Nokogiri::XML::SyntaxError` — parsing is strict, so malformed input is
+  never silently repaired and reported as conforming;
+* a missing nokogiri gem raises `Lutaml::Xml::Error::XmlConfigurationError`;
+* a class using the macro without an XML root mapping raises
+  `Lutaml::Model::TypeOnlyMappingError` from `validate`, since validation
+  must serialize the model to check it.
+
 
 == Validation examples
 

data/docs/_tutorials/xml-element-attribute-namespace-guide.adoc

@@ -9,6 +9,8 @@ This guide explains how XML namespaces work, particularly the distinction betwee
 - **Qualified**: Element/attribute needs a namespace declared in the XML
 - **Unqualified**: Element/attribute does not need a namespace declared (uses parent's namespace)
 
+> **Authoritative reference:** For the `element_form_default` / `form:` system, the full qualification precedence ladder, and `form:` behavior on nested `Serializable` children, see [docs/_guides/xml-namespace-qualification.adoc](../_guides/xml-namespace-qualification.adoc). This tutorial is a conceptual introduction.
+
 ## Default Namespace Inheritance
 
 **Critical Rule:** Default namespace inheritance ONLY applies to elements, NOT attributes.

data/docs/_tutorials/xml-schema-primer-style-guide.adoc

@@ -441,6 +441,8 @@ end
 
 NOTE: The `<comment>` element uses `xmlns=""` to explicitly declare blank namespace (form: :unqualified override).
 
+TIP: The `form:` option also works on attributes whose value type is a nested `Serializable` model, not just simple types like `:string`. It is a per-rule override and does not propagate transitively to grandchildren. For the full qualification precedence ladder and worked nested-model examples, see link:../_guides/xml-namespace-qualification/#form-override-on-serializable-children[XML Namespace Qualification and Prefix Control].
+
 == Section 3: Type Namespaces
 
 === General

data/docs/namespace-management.adoc

@@ -6,6 +6,8 @@
 
 This guide provides comprehensive information about XML namespace management in Lutaml::Model, including the `namespace_scope` directive, W3C compliance, and best practices for multi-namespace documents.
 
+NOTE: This guide focuses on namespace *declaration* and *scope*. For the `element_form_default` / `form:` qualification system — including the precedence ladder and `form:` behavior on nested `Serializable` children — see the companion guide: link:./_guides/xml-namespace-qualification[XML Namespace Qualification and Prefix Control].
+
 == Understanding XML Namespaces
 
 XML namespaces provide a method to avoid element name conflicts by qualifying names used in XML documents through a URI reference.

data/docs/xml-schema-qualification.md

@@ -13,6 +13,12 @@ declared in the XML, "unqualified" means the ELEMENT/ATTRIBUTE does not need a
 namespace declared in the XML (i.e. we look to its parent's namespace to find
 its namespace).
 
+> **Authoritative reference:** For the full qualification precedence ladder,
+> `form:` behavior on nested `Serializable` children, per-rule vs transitive
+> scope, and worked examples, see
+> [docs/_guides/xml-namespace-qualification.adoc](./_guides/xml-namespace-qualification.adoc).
+> This document is a conceptual overview; the guide is the canonical reference.
+
 When there is no XML Schema present:
 * element "acts like" unqualified (because of default namespace inheritance, does not need prefix)
 * attribute "acts like" qualified (because of no default namespace inheritance, requires prefix)

data/lib/compat/opal/generate_boot.rb

@@ -0,0 +1,123 @@
+# frozen_string: true
+
+# One-shot generator for lib/compat/opal/lutaml_model_boot.rb.
+#
+# Walks lib/lutaml/**/*.rb and extracts every `autoload :Name, "path"`
+# declaration (single-line or multi-line), resolving the standard
+# `"#{__dir__}/..."` and `"#{File.dirname(__FILE__)}/..."` interpolation
+# patterns relative to the declaring file's directory.
+#
+# Opal treats autoload as a no-op, so every autoload target must appear
+# here as an explicit `require` for nested constants to resolve at runtime.
+#
+# Run after adding/removing any autoload in lib/lutaml/:
+#   ruby lib/compat/opal/generate_boot.rb
+
+require "pathname"
+
+REPO_ROOT = Pathname.new(File.expand_path("../../..", __dir__))
+LIB       = REPO_ROOT.join("lib")
+
+# Patterns excluded under Opal because they pull in native-only deps
+# (Nokogiri/Ox C extensions, Thor CLI, etc.). REXML is pure Ruby and
+# ships in the bundled gem + moxml's lib/compat/opal/rexml/* shadows,
+# so it is NOT excluded — it is a fully working second Opal adapter.
+NATIVE_ONLY_PATTERNS = [
+  %r{(nokogiri|ox)_adapter\z},
+  %r{/schema/(relaxng|xsd)\b},
+  %r{/schema_builder/(nokogiri|oga)\b},
+  %r{/schema/builder/(nokogiri|oga)\b},
+  %r{\Alutaml/model/cli\z},
+].freeze
+
+# Match `autoload :Name, "...anything..."` where the string argument may
+# span multiple physical lines (whitespace after the comma).
+DECL_RE = /autoload\s+:[A-Za-z0-9_]+\s*,\s*"([^"]+)"/
+
+# Stitches multi-line autoload declarations into a single logical line so
+# DECL_RE can match. We only merge when the line ends right after the
+# comma that follows `autoload :Name`.
+def join_multiline_autoloads(src)
+  src.gsub(/(autoload\s+:[A-Za-z0-9_]+\s*,)\s*\n\s*/) { "#{Regexp.last_match(1)} " }
+end
+
+# Resolve an autoload's raw string argument to a require path relative to
+# LIB. Both common interpolation shapes resolve relative to the declaring
+# file's directory, which is what MRI does for them.
+def resolve_path(raw, declaring_file)
+  declaring_dir = Pathname.new(declaring_file).dirname
+
+  if raw.start_with?("\#{__dir__}/")
+    subdir = raw.sub("\#{__dir__}/", "").delete_suffix(".rb")
+    (declaring_dir + subdir).relative_path_from(LIB).to_s.delete_suffix(".rb")
+  elsif raw.start_with?("\#{File.dirname(__FILE__)}/")
+    subdir = raw.sub("\#{File.dirname(__FILE__)}/", "").delete_suffix(".rb")
+    (declaring_dir + subdir).relative_path_from(LIB).to_s.delete_suffix(".rb")
+  elsif raw.start_with?("lutaml/")
+    raw.delete_suffix(".rb")
+  else
+    raw.delete_suffix(".rb")
+  end
+end
+
+paths = []
+Dir.glob("#{LIB}/lutaml/**/*.rb").each do |file|
+  src = File.read(file)
+  # Strip full-line and trailing comments so commented-out autoload
+  # examples (e.g. in type_registry.rb) don't end up in the boot file.
+  src = src.lines.reject { |line| line.lstrip.start_with?("#") }.join
+  join_multiline_autoloads(src).scan(DECL_RE).each do |(raw)|
+    paths << resolve_path(raw, file)
+  end
+end
+
+paths = paths.uniq.sort
+native_only = paths.select { |p| NATIVE_ONLY_PATTERNS.any? { |re| p =~ re } }
+opal_paths  = paths - native_only
+
+# Order matters: namespace-defining entry files must load before any of
+# their nested files. lutaml/model.rb declares the Lutaml::Model module
+# (referenced by every other file); lutaml/xml.rb declares Lutaml::Xml.
+# After the entry files, load by depth-then-name so a parent file (e.g.
+# lutaml/hash_format.rb) is required before its children (e.g.
+# lutaml/hash_format/adapter/document.rb).
+#
+# ENTRY_FILES are added unconditionally: they are top-level entry points
+# that nothing else autoloads (because they ARE the entry points users
+# require directly), so they would otherwise be missing from the list.
+ENTRY_FILES = %w[lutaml/model lutaml/xml].freeze
+remaining = (opal_paths - ENTRY_FILES).sort_by { |p| [p.count("/"), p] }
+ordered   = ENTRY_FILES + remaining
+
+out = []
+out << "# frozen_string_literal: true"
+out << ""
+out << "# DO NOT EDIT — regenerate with:"
+out << "#   ruby lib/compat/opal/generate_boot.rb"
+out << "#"
+out << "# Opal does not support Ruby autoload (it is a no-op at parse time)."
+out << "# This file explicitly requires every autoload target in lib/lutaml/**"
+out << "# so that nested constants resolve at runtime under Opal."
+out << "#"
+out << "# Native-only paths excluded under Opal:"
+out << "#   - nokogiri/ox/rexml adapters (C extensions unavailable)"
+out << "#   - XSD / RELAX NG schema generators (require Nokogiri)"
+out << "#   - lutaml/model/cli (thor-based, runtime-irrelevant under Opal)"
+out << "#"
+out << "# Ordering: lutaml/model and lutaml/xml define the Lutaml::Model and"
+out << "# Lutaml::Xml namespaces, so they load first. Remaining paths are"
+out << "# ordered by depth (shallower first) so parent files declare their"
+out << "# child namespaces before children load."
+out << "#"
+out << "# Loaded by the Opal Rakefile before spec_helper."
+out << ""
+ordered.each { |p| out << %(require "#{p}") }
+out << ""
+
+# OPAL_BOOT_OUTPUT lets the in-sync guard spec regenerate to a temp path
+# without clobbering the committed manifest; unset, it writes canonically.
+target = ENV.fetch("OPAL_BOOT_OUTPUT") do
+  File.expand_path("lutaml_model_boot.rb", __dir__)
+end
+File.write(target, out.join("\n"))
+warn "Generated #{ordered.size} requires (excluded #{native_only.size} native-only paths) -> #{target}"

data/lib/compat/opal/js_bundle_entry.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# JS bundle entry point. Pulls in the Opal-only compat shims and boot
+# files BEFORE lutaml/model so that moxml's adapter constants, the
+# String/Encoding/YAML/Array#pack patches, and the eager-loaded
+# Moxml::* / Lutaml::* constants are all in place by the time
+# lib/lutaml/model.rb runs.
+#
+# Used by scripts/build.rb as the bundle ENTRY (instead of
+# "lutaml/model" directly) so the JS bundle mirrors the load order
+# that lutaml-model's Rakefile applies for `rake spec:opal`.
+
+if RUBY_ENGINE == "opal"
+  # 0. runtime_compatibility first: it stubs Mutex/ConditionVariable/
+  #    Thread/WeakRef and patches Module#prepend for Opal. Oga's LRU
+  #    and other gems reference Mutex at file-load time, so this must
+  #    run before any gem that touches thread-safety primitives.
+  require "lutaml/model/runtime_compatibility"
+
+  # 0a. Opal's stdlib StringIO < IO loads here so moxml's
+  #     `class StringIO` (bare, no parent) in rexml_compat.rb re-opens
+  #     the existing class instead of conflicting with `< ::IO`.
+  #     Without this, the bare-class definition runs first and Opal's
+  #     `< IO` definition later raises "superclass mismatch".
+  require "stringio"
+
+  # 1. stdlib shims: String/Encoding/StringIO + Array#pack + nodejs/yaml
+  require "rexml_compat"
+  require "yaml_compat"
+
+  # 2. forks' Opal-aware conditionals select the pure-Ruby lexer
+  require "oga"
+  require "ll/setup"
+
+  # 3. eager-load boots (Opal ignores autoload)
+  require "moxml_boot"
+  require "lutaml_model_boot"
+end
+
+# 4. the actual entry point
+require "lutaml/model"
+require "lutaml/xml"