lutaml-model 0.8.11 → 0.8.13

data/RELEASE_NOTES.adoc

@@ -26,7 +26,7 @@ The `namespace_scope` directive allows you to control WHERE namespace declaratio
 ----
 class Vcard < Lutaml::Model::Serializable
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     # Consolidate namespaces at root
@@ -145,7 +145,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll
   end
 end
@@ -209,7 +209,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_nil: :omit
   end
 

data/benchmark/quick_benchmark.rb

@@ -30,7 +30,7 @@ class Item < Lutaml::Model::Serializable
   attribute :value, :float
 
   xml do
-    root "item"
+    element "item"
     map_attribute "id", to: :id
     map_element "name", to: :name
     map_element "value", to: :value
@@ -47,7 +47,7 @@ class Container < Lutaml::Model::Serializable
   attribute :items, Item, collection: true
 
   xml do
-    root "container"
+    element "container"
     map_element "item", to: :items
   end
 

data/benchmark/serialization_benchmark.rb

@@ -49,7 +49,7 @@ class SimpleModel < Lutaml::Model::Serializable
   attribute :created_at, :date_time
 
   xml do
-    root "simple"
+    element "simple"
     map_attribute "id", to: :id
     map_element "name", to: :name
     map_element "active", to: :active
@@ -79,7 +79,7 @@ class AddressModel < Lutaml::Model::Serializable
   attribute :postal_code, :string
 
   xml do
-    root "address"
+    element "address"
     map_element "street", to: :street
     map_element "city", to: :city
     map_element "country", to: :country
@@ -106,7 +106,7 @@ class PersonModel < Lutaml::Model::Serializable
   attribute :tags, :string, collection: true
 
   xml do
-    root "person"
+    element "person"
     map_attribute "id", to: :id
     map_element "first_name", to: :first_name
     map_element "last_name", to: :last_name
@@ -136,7 +136,7 @@ class DepartmentModel < Lutaml::Model::Serializable
   attribute :employees, PersonModel, collection: true
 
   xml do
-    root "department"
+    element "department"
     map_element "name", to: :name
     map_element "code", to: :code
     map_element "employee", to: :employees

data/docs/_guides/advanced-mapping.adoc

@@ -47,7 +47,7 @@ class CustomModel < Lutaml::Model::Serializable
   end
 
   xml do
-    root "CustomModel"
+    element "CustomModel"
     map_element ["name", "custom-name"], with: { to: :name_to_xml, from: :name_from_xml }
     map_element ["color", "shade"], with: { to: :color_to_xml, from: :color_from_xml }
     map_attribute ["id", "identifier"], to: :id

data/docs/_guides/character-encoding.adoc

@@ -79,7 +79,7 @@ class JapaneseCeramic < Lutaml::Model::Serializable
   attribute :description, :string
 
   xml do
-    root 'JapaneseCeramic'
+    element "JapaneseCeramic"
     map_attribute 'glazeType', to: :glaze_type
     map_element 'description', to: :description
   end
@@ -140,7 +140,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :temperature, :integer
 
   xml do
-    root 'ceramic'
+    element "ceramic"
     map_element 'potter', to: :potter
     map_content to: :description
   end
@@ -191,7 +191,7 @@ class JapaneseCeramic < Lutaml::Model::Serializable
   attribute :description, :string
 
   xml do
-    root 'JapaneseCeramic'
+    element "JapaneseCeramic"
     map_attribute 'glazeType', to: :glaze_type
     map_element 'description', to: :description
   end

data/docs/_guides/index.adoc

@@ -46,6 +46,10 @@ See link:../references/rdf-namespaces[RDF Namespaces] for namespace classes,
 * link:../consolidation-mapping[Consolidation Mapping] - Group sibling elements into structured models
 * link:../document-validation[Document Validation] - Document-level validation with rules, profiles, and remediation
 
+== Runtime environments
+
+* link:../opal[Opal Usage Guide] - Run Lutaml::Model in the browser via Opal (Ruby to JavaScript)
+
 == By task
 
 === I want to serialize to XML

data/docs/_guides/missing-values-handling.adoc

@@ -1246,7 +1246,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_nil: :omit
   end
 
@@ -1285,7 +1285,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_nil: :as_nil
   end
 
@@ -1327,7 +1327,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_nil: :as_blank # <1>
   end
 
@@ -1424,7 +1424,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_empty: :omit
   end
 
@@ -1461,7 +1461,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_empty: :as_nil
   end
 
@@ -1503,7 +1503,7 @@ class SomeModel < Lutaml::Model::Serializable
   attribute :coll, :string, collection: true
 
   xml do
-    root "some-model"
+    element "some-model"
     map_element 'collection', to: :coll, render_empty: :as_blank # <1>
   end
 

data/docs/_guides/ooxml-examples.adoc

@@ -101,7 +101,7 @@ class PersonName < Lutaml::Model::Serializable
   attribute :suffix, :string
 
   xml do
-    root "personName"
+    element "personName"
     map_element "givenName", to: :given_name
     map_element "surname", to: :surname
     map_attribute "prefix", to: :prefix
@@ -114,7 +114,7 @@ class Contact < Lutaml::Model::Serializable
   attribute :person_name, PersonName
 
   xml do
-    root "ContactInfo"
+    element "ContactInfo"
     map_element "personName", to: :person_name
   end
 end
@@ -233,7 +233,7 @@ class DctermsCreated < Lutaml::Model::Serializable
   attribute :type, XsiTypeType
 
   xml do
-    root "created"
+    element "created"
     namespace DctermsNamespace
     map_attribute "type", to: :type
     map_content to: :value
@@ -246,7 +246,7 @@ class DctermsModified < Lutaml::Model::Serializable
   attribute :type, XsiTypeType
 
   xml do
-    root "modified"
+    element "modified"
     namespace DctermsNamespace
     map_attribute "type", to: :type
     map_content to: :value
@@ -263,7 +263,7 @@ class CoreProperties < Lutaml::Model::Serializable
   attribute :modified, DctermsModified
 
   xml do
-    root "coreProperties"
+    element "coreProperties"
     map_element "title", to: :title
     map_element "creator", to: :creator
     map_element "lastModifiedBy", to: :last_modified_by
@@ -420,7 +420,7 @@ class Settings < Lutaml::Model::Serializable
   attribute :chart_tracking, :boolean
 
   xml do
-    root "settings"
+    element "settings"
     namespace WNamespace
     namespace_scope [W14Namespace, W15Namespace]
 
@@ -655,7 +655,7 @@ class Settings < Lutaml::Model::Serializable
   attribute :w15_doc_id, W15DocId
 
   xml do
-    root "settings"
+    element "settings"
     namespace WNamespace
     namespace_scope [W14Namespace, W15Namespace]
 

data/docs/_guides/opal.adoc

@@ -0,0 +1,221 @@
+---
+title: Opal Usage Guide
+parent: Guides
+nav_order: 99
+---
+
+= Opal Usage Guide
+
+:toc:
+:toclevels: 3
+
+== Overview
+
+https://opalrb.com[Opal] is a Ruby-to-JavaScript compiler that allows Ruby code to run in the browser. Lutaml::Model supports running under Opal, enabling XML/JSON/YAML serialization in client-side applications.
+
+The XML parsing layer is provided by the https://github.com/lutaml/moxml[moxml] gem (v0.2+), which detects the Opal runtime and uses the REXML adapter automatically.
+
+== How it works
+
+Opal compiles Ruby source code to JavaScript. Under Opal:
+
+. `RUBY_ENGINE` equals `"opal"`
+. `Lutaml::Model::RuntimeCompatibility.opal?` returns `true`
+. Adapter selection is adjusted automatically
+. Gems with C extensions (Nokogiri, Ox, Oj, tomlib) are not available
+. REXML is used for XML because Opal reimplements `strscan` and `stringio` in its stdlib, enabling REXML (pure Ruby) to compile cleanly to JavaScript
+
+No configuration is needed -- the runtime is detected and adapters are selected automatically.
+
+== Supported features
+
+=== Fully supported
+
+* Model definition with `attribute`, types, collections, defaults
+* XML serialization/deserialization (via REXML adapter)
+** Element and attribute mapping
+** Nested elements and collections
+** Mixed content
+** Namespaces (parsing and serialization)
+** CDATA sections
+** Processing instructions
+** Comments
+** Entity references
+** XML declarations and doctypes
+* JSON serialization/deserialization (via standard adapter)
+* YAML serialization/deserialization (via standard adapter)
+* Hash transformation
+* Custom types
+* Model import (`import_model`)
+* Value transformations
+
+=== Not available
+
+[cols="1,3",options="header"]
+|===
+| Feature | Reason
+| XSD schema generation | Requires Nokogiri
+| RELAX NG generation | Requires Nokogiri
+| XML schema compilation | Requires Nokogiri + native parsing
+| TOML serialization | Both tomlib and toml-rb require native extensions
+| Oj / MultiJson adapters | Require native extensions
+| Ox / Nokogiri / Oga adapters | Require native extensions or C extensions
+| XPath queries | REXML XPath requires features not yet in Opal's stdlib
+| Liquid templating | Uses file-system-based template loading (Phase 1: skipped)
+| Canon XML equivalence | Uses Nokogiri for XML parsing
+|===
+
+== Setup
+
+=== Gemfile
+
+Add Opal gems to your Gemfile:
+
+[source,ruby]
+----
+gem "lutaml-model"
+
+group :opal do
+  gem "opal", "~> 1.8"
+  gem "opal-rspec", "~> 1.0"
+  gem "opal-sprockets"
+end
+----
+
+=== Rake task
+
+Add an Opal RSpec task to your Rakefile:
+
+[source,ruby]
+----
+begin
+  require "opal/rspec/rake_task"
+rescue LoadError
+  # Opal not available
+end
+
+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"
+      runner.default_path = "spec"
+      runner.pattern = "spec/**/*_spec.{rb,opal}"
+    end
+  end
+end
+----
+
+=== Test configuration
+
+Create `spec/support/opal.rb` for Opal-specific test patches:
+
+[source,ruby]
+----
+# frozen_string_literal: true
+
+if RUBY_ENGINE == "opal"
+  Lutaml::Model::Config.xml_adapter_type = :rexml
+end
+----
+
+Create `.rspec-opal`:
+
+----
+--default-path=spec
+--pattern='spec/**/*_spec.{rb,opal}'
+-I lib
+--opal-opt=-g,lutaml-model
+-I spec
+--require=spec_helper
+--require=support/opal
+----
+
+=== CI workflow
+
+Add `.github/workflows/opal.yml`:
+
+[source,yaml]
+----
+name: opal
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: "recursive"
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: "3.3"
+          bundler-cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "18"
+      - name: Run Opal tests
+        run: bundle exec rake spec:opal
+----
+
+== Example: XML round-trip in the browser
+
+[source,ruby]
+----
+class Person
+  include Lutaml::Model::Serialize
+
+  attribute :name, :string
+  attribute :age, :integer
+
+  xml do
+    element "person"
+    map_element "name", to: :name
+    map_element "age", to: :age
+  end
+end
+
+# Parse XML
+person = Person.from_xml('<person><name>Alice</name><age>30</age></person>')
+person.name  # => "Alice"
+person.age   # => 30
+
+# Serialize to XML
+person.to_xml  # => "<person><name>Alice</name><age>30</age></person>"
+
+# JSON and YAML also work
+person.to_json  # => '{"name":"Alice","age":30}'
+person.to_yaml  # => "---\nname: Alice\nage: 30\n"
+----
+
+== Architecture
+
+Under Opal, the library uses a JRuby-like pattern for dependency management:
+
+. *Dependencies stay in the gemspec.* Gems like Nokogiri, Ox, and Oga remain listed as dependencies -- they are simply not loadable under Opal.
+. *Requires are guarded with `RUBY_ENGINE`.* Code that depends on native gems uses `RUBY_ENGINE == "opal"` checks instead of silent `rescue LoadError`.
+. *No gem splitting.* The same gem works on both MRI and Opal.
+
+Key components:
+* `Lutaml::Model::RuntimeCompatibility` -- detects the runtime (opal, windows, native)
+* `Lutaml::Model::AdapterResolver` -- selects adapters based on runtime capabilities
+* `Moxml::Config::OPAL_DEFAULT_ADAPTER` -- set to `:rexml`
+* `Moxml::Adapter::OPAL_AVAILABLE_ADAPTERS` -- set to `%i[rexml]`
+
+== Dependencies
+
+The following gems in the lutaml ecosystem support Opal:
+
+* **lutaml-model** -- Core model library (this gem)
+* **moxml** (v0.2+) -- XML parsing abstraction with REXML adapter for Opal
+* **canon** -- XML comparison (uses moxml under Opal; comparison features work but Nokogiri-specific features do not)
+
+== Limitations
+
+* **No XPath** -- REXML's XPath module has dependencies not yet reimplemented in Opal's stdlib.
+* **No schema generation** -- XSD, RELAX NG generation, and schema compilation require Nokogiri.
+* **No TOML** -- Both TOML adapters (tomlib, toml-rb) require native extensions.
+* **No Liquid** -- Template rendering via Liquid is skipped in Opal (file-system dependency). May be addressed in a future phase using liquidjs via Opal's JavaScript bridge.

data/docs/_guides/value-transformations.adoc

@@ -275,7 +275,7 @@ class Event < Lutaml::Model::Serializable
   attribute :event_date, MultiFormatDate
 
   xml do
-    root "event"
+    element "event"
     map_element "eventDate", to: :event_date
   end
 
@@ -402,7 +402,7 @@ class Document < Lutaml::Model::Serializable
   }
 
   xml do
-    root "document"
+    element "document"
     map_element "pubDate", to: :publication_date
   end
 
@@ -505,7 +505,7 @@ class Document < Lutaml::Model::Serializable
 
   # XML wants YYYYMMDD
   xml do
-    root "document"
+    element "document"
     map_element "pubDate", to: :publication_date, transform: {
       export: ->(date) { date&.strftime("%Y%m%d") },
       import: ->(str) {
@@ -749,7 +749,7 @@ class Product < Lutaml::Model::Serializable
   end
 
   xml do
-    root "product"
+    element "product"
     map_element "name", to: :name, transform: {
       export: ->(value) { "XML:#{value}" },
       import: ->(value) { value.gsub("XML:", "") }
@@ -898,7 +898,7 @@ class Event < Lutaml::Model::Serializable
   attribute :name, :string
 
   xml do
-    root "event"
+    element "event"
     map_element "eventDate", to: :event_date
     map_element "name", to: :name
   end
@@ -1029,7 +1029,7 @@ class Schedule < Lutaml::Model::Serializable
   attribute :activity, :string
 
   xml do
-    root "schedule"
+    element "schedule"
     map_element "date", to: :week_date
     map_element "activity", to: :activity
   end
@@ -1100,7 +1100,7 @@ class BlogPost < Lutaml::Model::Serializable
 
   # XML API requires YYYYMMDD
   xml do
-    root "post"
+    element "post"
     map_element "publishDate", to: :published_on, transform: {
       export: ->(date) { date&.strftime("%Y%m%d") },
       import: ->(str) {

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

@@ -185,7 +185,7 @@ class NamespacedItem < Lutaml::Model::Serializable
   attribute :alt_name, SecondNamespacedName # SecondNamespace
 
   xml do
-    root "item"
+    element "item"
     namespace SecondNamespace  # Root uses SecondNamespace
     map_element "name", to: :name
     map_element "alt_name", to: :alt_name

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

@@ -43,7 +43,7 @@ class NativeItem < Lutaml::Model::Serializable
   attribute :name, :string  # Native type with no inherent namespace
 
   xml do
-    root "first_item"
+    element "first_item"
     namespace FirstItemNamespace
     map_element "name", to: :name
   end
@@ -97,7 +97,7 @@ class NamespacedItem < Lutaml::Model::Serializable
   attribute :alt_name, SecondNamespacedName # Has SecondNamespace
 
   xml do
-    root "second_item"
+    element "second_item"
     namespace SecondNamespace
     map_element "name", to: :name
     map_element "alt_name", to: :alt_name
@@ -127,7 +127,7 @@ class NestedItem < Lutaml::Model::Serializable
   attribute :value, :string
 
   xml do
-    root "nested"
+    element "nested"
     namespace FirstNamespace
     map_element "value", to: :value
   end
@@ -137,7 +137,7 @@ class Container < Lutaml::Model::Serializable
   attribute :item, NestedItem
 
   xml do
-    root "container"
+    element "container"
     namespace SecondNamespace
     map_element "item", to: :item
   end
@@ -162,7 +162,7 @@ end
 [source,ruby]
 ----
 xml do
-  root "item"
+  element "item"
   namespace MyNamespace
   map_attribute "id", to: :id          # Unqualified (no namespace)
   map_element "name", to: :name         # Qualified (uses MyNamespace)
@@ -200,7 +200,7 @@ class Item < Lutaml::Model::Serializable
   attribute :value, :integer
 
   xml do
-    root "item"
+    element "item"
     namespace MyNamespace
     map_attribute "id", to: :id
     map_attribute "value", to: :value
@@ -280,7 +280,7 @@ class Spacing < Lutaml::Model::Serializable
   attribute :before, :integer
 
   xml do
-    root "spacing"
+    element "spacing"
     namespace WordProcessingML
     map_attribute "val", to: :val
     map_attribute "after", to: :after
@@ -330,7 +330,7 @@ class Item < Lutaml::Model::Serializable
   attribute :explicit, :string
 
   xml do
-    root "item"
+    element "item"
     namespace Namespace1
     map_attribute "normal", to: :normal           # Uses form_default (unqualified)
     map_attribute "explicit", to: :explicit, namespace: Namespace2  # Explicit wins
@@ -397,7 +397,7 @@ class NativeItemNames < Lutaml::Model::Serializable
   attribute :name, :string, collection: true
 
   xml do
-    root "item_names"
+    element "item_names"
     namespace FirstItemNamespace
     map_element "name", to: :name
   end
@@ -422,7 +422,7 @@ class NativeItemCollection < Lutaml::Model::Serializable
   attribute :items, NativeItem, collection: true
 
   xml do
-    root "items"
+    element "items"
     namespace FirstItemNamespace
     map_element "item", to: :items
   end
@@ -441,7 +441,7 @@ class Container < Lutaml::Model::Serializable
   attribute :items, BaseItem, collection: true, polymorphic: [TypeA, TypeB]
 
   xml do
-    root "container"
+    element "container"
     map_element "item", to: :items
   end
 end
@@ -557,7 +557,7 @@ class Child < Lutaml::Model::Serializable
   attribute :value, :string
 
   xml do
-    root "child"
+    element "child"
     # No namespace declared - will inherit from parent
     map_element "value", to: :value
   end
@@ -567,7 +567,7 @@ class Parent < Lutaml::Model::Serializable
   attribute :child, Child
 
   xml do
-    root "parent"
+    element "parent"
     namespace ParentNamespace
     map_element "child", to: :child
   end
@@ -594,7 +594,7 @@ class Wrapper < Lutaml::Model::Serializable
   attribute :items, NamespacedItem, collection: true
 
   xml do
-    root "wrapper"
+    element "wrapper"
     namespace WrapperNamespace
     map_element "item", to: :items
   end
@@ -635,7 +635,7 @@ class PlainItem < Lutaml::Model::Serializable
   attribute :name, :string
 
   xml do
-    root "item"
+    element "item"
     # No namespace declared
     map_element "name", to: :name
   end