lutaml-model 0.8.17 → 0.8.19

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/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"