lutaml-model 0.8.11 → 0.8.13

data/docs/_guides/xml_mappings/07_best_practices.adoc

@@ -46,14 +46,14 @@ end
 # Repeat namespace details in every model
 class Model1 < Lutaml::Model::Serializable
   xml do
-    root 'model1'
+    element "model1"
     namespace 'https://example.com/project/v1', 'proj'
   end
 end
 
 class Model2 < Lutaml::Model::Serializable
   xml do
-    root 'model2'
+    element "model2"
     namespace 'https://example.com/project/v1', 'proj'
   end
 end
@@ -134,7 +134,7 @@ class Document < Lutaml::Model::Serializable
   attribute :creator, DcCreatorType
 
   xml do
-    root 'document'
+    element "document"
     map_element 'title', to: :title      # dc:title automatically
     map_element 'creator', to: :creator  # dc:creator automatically
   end
@@ -145,7 +145,7 @@ class BookMetadata < Lutaml::Model::Serializable
   attribute :creator, DcCreatorType
 
   xml do
-    root 'book'
+    element "book"
     map_element 'title', to: :title      # dc:title automatically
     map_element 'creator', to: :creator  # dc:creator automatically
   end
@@ -162,7 +162,7 @@ class Document < Lutaml::Model::Serializable
   attribute :creator, :string
 
   xml do
-    root 'document'
+    element "document"
     # Repetitive and error-prone
     map_element 'title', to: :title,
       namespace: 'http://purl.org/dc/elements/1.1/', prefix: 'dc'
@@ -181,7 +181,7 @@ end
 # Consolidate frequently-used namespaces at root
 class Vcard < Lutaml::Model::Serializable
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
     namespace_scope [VcardNamespace, DcNamespace, DctermsNamespace]
 
@@ -206,7 +206,7 @@ end
 # Without namespace_scope for multi-namespace documents
 class Vcard < Lutaml::Model::Serializable
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
     # No namespace_scope
 
@@ -236,7 +236,7 @@ class Ceramic < Lutaml::Model::Serializable
     element 'ceramic'
     namespace CeramicNamespace
     # namespace_scope [CeramicNamespace]  # NOT NEEDED - only one namespace
-    
+
     map_element 'type', to: :type
     map_element 'glaze', to: :glaze
   end
@@ -250,7 +250,7 @@ end
 # Keep rarely-used namespaces local for clarity
 class Document < Lutaml::Model::Serializable
   xml do
-    root 'document'
+    element "document"
     namespace DocumentNamespace
     namespace_scope [DocumentNamespace]  # Only frequently used
 
@@ -284,7 +284,7 @@ end
 ----
 class Model < Lutaml::Model::Serializable
   xml do
-    root 'model'  # Backward compatible, still works
+    element "model"  # Backward compatible, still works
     map_element 'attr', to: :attr
   end
 end
@@ -441,7 +441,7 @@ end
 ----
 class RichText < Lutaml::Model::Serializable
   xml do
-    root 'text', mixed: true # DEPRECATED - use mixed_content instead
+    element "text", mixed: true # DEPRECATED - use mixed_content instead
     map_element 'b', to: :bold
   end
 end
@@ -723,7 +723,8 @@ end
 
 * **Ox**: Fastest, use for performance-critical applications
 * **Nokogiri**: Most compatible, good balance
-* **Oga**: Pure Ruby, works with Opal, use when no native extensions allowed
+* **Oga**: Pure Ruby, use when no native extensions allowed
+* **REXML**: Pure Ruby (bundled with Ruby), Opal-compatible
 
 **Configure once:**
 

data/docs/_migrations/0-8-0-namespace-restructuring.adoc

@@ -1359,7 +1359,7 @@ Version 0.8.0 unifies the `xml do` syntax for both model classes and custom Type
 class Person < Lutaml::Model::Serializable
   xml do
     namespace "http://example.com/ns", "p"  # Different syntax
-    root "person"
+    element "person"
   end
 end
 
@@ -1485,7 +1485,7 @@ Version 0.8.0 enforces **model-centric namespace definitions**. Namespaces are d
 ----
 class Parent < Lutaml::Model::Serializable
   xml do
-    root "parent"
+    element "parent"
     namespace "http://parent.com", "p"
 
     # ❌ Namespace on mapping - NO LONGER SUPPORTED

data/docs/_pages/attributes.adoc

@@ -808,7 +808,7 @@ class ReferenceSet < Lutaml::Model::Serializable
   ]
 
   xml do
-    root "ReferenceSet"
+    element "ReferenceSet"
 
     map_element "reference", to: :references, polymorphic: {
       # This refers to the attribute in the polymorphic model, you need
@@ -945,7 +945,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
 

data/docs/_pages/collections.adoc

@@ -145,7 +145,7 @@ class TitleDelimiterCollection < Lutaml::Model::Collection
   instances :items, :string
 
   xml do
-    root "titles"
+    element "titles"
     map_attribute "title", to: :items, delimiter: "; " <1>
   end
 end
@@ -164,7 +164,7 @@ class TitleCollection < Lutaml::Model::Collection
   instances :items, :string
 
   xml do
-    root "titles"
+    element "titles"
     map_attribute "title", to: :items, as_list: {
       import: ->(str) { str.split("; ") }, <1>
       export: ->(arr) { arr.join("; ") }, <2>
@@ -302,7 +302,6 @@ class TitleCollection < Lutaml::Model::Collection
   instances :titles, Title
 
   key_value do
-    no_root # default
     map_instances to: :titles
   end
 end
@@ -382,7 +381,6 @@ class TitleCollection < Lutaml::Model::Collection
   instances :titles, Title
 
   key_value do
-    no_root # default
     map_instances to: :titles
   end
 end
@@ -477,11 +475,11 @@ class MyCollection < Lutaml::Model::Collection
   instances :items, ModelType
 
   xml do
-    root "name-of-xml-container-element"
+    element "name-of-xml-container-element"
   end
 
   key_value do
-    root "name-of-key-value-container-element"
+    key "name-of-key-value-wrapper-key"
   end
 end
 
@@ -490,6 +488,15 @@ class ModelType < Lutaml::Model::Serializable
 end
 ----
 
+In the `key_value` block:
+
+- `key "key-name"` sets the wrapper key for the collection in key-value formats (JSON, YAML, TOML).
+  The serialized output wraps all instances under this key (e.g., `{"titles": [...]}`).
+- Without a `key` call (the default), instances are serialized directly at the top level
+  (e.g., `["Item One", "Item Two"]`).
+
+NOTE: Key-value formats use `key` to set the wrapper key name, and `element` for XML element names.
+
 A named collection can alternatively be implemented as a non-collection model
 ("Model class with an attribute") that contains the collection of instances. In
 this case, the attribute will be an Array object, which does not contain
@@ -504,7 +511,7 @@ class Title < Lutaml::Model::Serializable
   attribute :title, :string
 
   xml do
-    root "title"
+    element "title"
     map_content to: :title
   end
 end
@@ -513,7 +520,7 @@ class DirectTitleCollection < Lutaml::Model::Collection
   instances :items, Title
 
   xml do
-    root "titles"
+    element "titles"
     map_element "title", to: :items
   end
 
@@ -639,7 +646,7 @@ class Title < Lutaml::Model::Serializable
   attribute :title, :string
 
   xml do
-    root "title"
+    element "title"
     map_element "content", to: :title
   end
 
@@ -652,12 +659,12 @@ class TitleCollection < Lutaml::Model::Collection
   instances :items, Title
 
   xml do
-    root "titles"
+    element "titles"
     map_element 'title', to: :items
   end
 
   key_value do
-    root "titles"
+    key "titles"
     map_instances to: :items
   end
 end
@@ -742,12 +749,12 @@ class BibliographicItem < Lutaml::Model::Serializable
   attribute :title_parts, :string, collection: StringParts
 
   xml do
-    root "titles"
+    element "titles"
     map_element "title", to: :title_parts
   end
 
   key_value do
-    root "titles"
+    key "titles"
     map_instances to: :title_parts
   end
 
@@ -829,7 +836,7 @@ class TitleCollection < Lutaml::Model::Collection
   instances :items, Title
 
   xml do
-    root "title-group"
+    element "title-group"
     map_element "artifact", to: :items
   end
 end
@@ -838,7 +845,7 @@ class BibItem < Lutaml::Model::Serializable
   attribute :titles, TitleCollection
 
   xml do
-    root "bibitem"
+    element "bibitem"
     # This overrides the collection's root "title-group"
     map_element "titles", to: :titles
   end
@@ -1367,12 +1374,11 @@ class OrderedItemCollection < Lutaml::Model::Collection
   ordered by: :id, order: :desc
 
   xml do
-    root "items"
+    element "items"
     map_element "item", to: :items
   end
 
   key_value do
-    no_root
     map_instances to: :items
   end
 end
@@ -1401,7 +1407,7 @@ class ProcOrderedItemCollection < Lutaml::Model::Collection
   ordered by: ->(item) { [item.name.length, item.name] }, order: :asc
 
   xml do
-    root "items"
+    element "items"
     map_element "item", to: :items
   end
 end
@@ -1543,7 +1549,7 @@ class ReferenceSet < Lutaml::Model::Collection
   ]
 
   xml do
-    root "ReferenceSet"
+    element "ReferenceSet"
     map_instances to: :references, polymorphic: {
       attribute: "_class",
       class_map: {
@@ -1640,7 +1646,7 @@ class ReferenceSet < Lutaml::Model::Collection
   ]
 
   xml do
-    root "ReferenceSet"
+    element "ReferenceSet"
     map_instances to: :references, polymorphic: {
       attribute: "_class",
       class_map: {

data/docs/_pages/configuration.adoc

@@ -74,7 +74,7 @@ When an adapter is needed for a format, `AdapterResolver` follows this chain:
 | Pure Ruby. No compilation needed. Opal-compatible.
 
 | `:rexml`
-| Pure Ruby. Bundled with Ruby (default gem).
+| Pure Ruby. Bundled with Ruby (default gem). Opal-compatible.
 |===
 
 === JSON adapters
@@ -261,8 +261,8 @@ end
 
 * **Nokogiri**: Most projects (default, best compatibility)
 * **Ox**: Performance-critical applications
-* **Oga**: Pure Ruby environments, Opal/JavaScript compilation
-* **REXML**: No extra gems, pure Ruby (bundled with Ruby)
+* **Oga**: Pure Ruby environments
+* **REXML**: No extra gems, pure Ruby (bundled with Ruby). Also used under Opal.
 
 === Choose JSON adapter based on
 
@@ -279,12 +279,14 @@ end
 
 Lutaml::Model supports running under https://opalrb.com[Opal] (Ruby compiled to JavaScript) with some limitations. The library detects the runtime automatically via `Lutaml::Model::RuntimeCompatibility` and adapts its behavior accordingly.
 
+The XML parsing layer is provided by the https://github.com/lutaml/moxml[moxml] gem, which has been updated to support Opal. Under Opal, moxml uses the REXML adapter because Opal reimplements `strscan` and `stringio` in its stdlib, enabling REXML (pure Ruby) to compile cleanly to JavaScript.
+
 === Adapter defaults on Opal
 
 [cols="1,2",options="header"]
 |===
 | Format | Behavior
-| XML | Only `:oga` is available (auto-selected). Nokogiri, Ox, and REXML require native extensions.
+| XML | Only `:rexml` is available (auto-selected). Opal reimplements strscan/stringio in its stdlib, enabling REXML to compile to JavaScript.
 | JSON | Only `:standard` is available. Oj and MultiJson require native extensions.
 | YAML | `:standard` (Psych ships with Opal's stdlib).
 | TOML | **Not available.** Both tomlib and toml-rb depend on native extensions.
@@ -299,6 +301,9 @@ The following features raise `NotImplementedError` when called under Opal:
 * `Lutaml::Model::Schema.to_relaxng` -- RELAX NG generation requires Nokogiri
 * `Lutaml::Model::Schema.from_xml` -- XML schema compilation is not supported
 * `Lutaml::Xml::Schema::Xsd::Base#to_formatted_xml` -- XSD formatted output requires the Canon gem
+* XPath queries -- REXML XPath requires features not yet supported by Opal's stdlib
+
+See the link:../guides/opal[Opal Usage Guide] for complete setup instructions and limitations.
 
 == See also
 

data/docs/_pages/consolidation-mapping.adoc

@@ -76,7 +76,7 @@ class TitleCollection < Lutaml::Model::Collection
   organizes :per_lang, PerLangTitleGroup
 
   xml do
-    root "titles"
+    element "titles"
     map_instances to: :items
 
     consolidate_map by: :lang, to: :per_lang do
@@ -105,7 +105,7 @@ class IndividualTitle < Lutaml::Model::Serializable
   attribute :content, :string
 
   xml do
-    root "title"
+    element "title"
     map_attribute "lang", to: :lang
     map_attribute "type", to: :type_of_title
     map_content to: :content
@@ -127,7 +127,7 @@ class TitleCollection < Lutaml::Model::Collection
   organizes :per_lang, PerLangTitleGroup
 
   xml do
-    root "titles"
+    element "titles"
     map_instances to: :items
 
     consolidate_map by: :lang, to: :per_lang do
@@ -147,7 +147,7 @@ class Bibdata < Lutaml::Model::Serializable
   attribute :titles, IndividualTitle, collection: TitleCollection
 
   xml do
-    root "bibdata"
+    element "bibdata"
     map_element "title", to: :titles
   end
 end

data/docs/_pages/importable_models.adoc

@@ -14,8 +14,9 @@ This feature works both with XML and key-value formats.
 
 * The import order determines how elements and attributes are overwritten.
 
-* An importable model with XML serialization mappings requires setting the model's
-XML serialization configuration with the `no_root` directive.
+* An importable model with XML serialization mappings is a "type-only model" —
+  it has no `element` declaration in its `xml` block, meaning it can only be
+  used as an embedded type through a parent model.
 
 The model can be imported into another model using the following directives:
 
@@ -25,11 +26,11 @@ The model can be imported into another model using the following directives:
 
 `import_model_mappings`:: imports only mappings.
 
-NOTE: Models with `no_root` can only be parsed through parent models.
-Direct calling `NoRootModel.from_xml` will raise a `NoRootMappingError`.
+NOTE: Type-only models (no `element` declaration) can only be parsed through parent models.
+Directly calling `TypeOnlyModel.from_xml` will raise a `TypeOnlyMappingError`.
 
 NOTE: Namespaces are not currently supported in importable models.
-If `namespace` is defined with `no_root`, `NoRootNamespaceError` will be raised.
+If `namespace` is defined with the deprecated `no_root`, `TypeOnlyNamespaceError` will be raised.
 
 .Importing model components using an importable model
 [example]
@@ -51,7 +52,7 @@ class GroupOfItems < Lutaml::Model::Serializable
   attribute :code, :string
 
   xml do
-    no_root
+    # Type-only model - no element declaration needed
     sequence do
       map_element "name", to: :name
       map_element "type", to: :type
@@ -67,7 +68,7 @@ class ComplexType < Lutaml::Model::Serializable
   import_model_attributes GroupOfItems
 
   xml do
-    root "GroupOfItems"
+    element "GroupOfItems"
 
     map_attribute "tag", to: :tag
     map_content to: :content
@@ -96,7 +97,7 @@ end
 [source,ruby]
 ----
 > parsed = GroupOfItems.from_xml(xml)
-> # Lutaml::Model::NoRootMappingError: "GroupOfItems has `no_root`, it allowed only for reusable models"
+> # Lutaml::Model::TypeOnlyMappingError: "GroupOfItems is a type-only model (no element declared), ..."
 ----
 ====
 
@@ -124,7 +125,7 @@ class Address < Lutaml::Model::Serializable
   attribute :zip, :string
 
   xml do
-    no_root
+    # Type-only model - no element declaration needed
 
     map_element :street, to: :street
     map_element :city, to: :city
@@ -137,7 +138,7 @@ class Person < Lutaml::Model::Serializable
   import_model_attributes Address
 
   xml do
-    root "Person"
+    element "Person"
 
     map_element :name, to: :name
     sequence do
@@ -193,7 +194,7 @@ class ContactEmail < Lutaml::Model::Serializable
   attribute :email, :string
 
   xml do
-    no_root
+    # Type-only model - no element declaration needed
 
     map_element :email, to: :email
   end
@@ -203,7 +204,7 @@ class ContactPhone < Lutaml::Model::Serializable
   attribute :phone, :string
 
   xml do
-    no_root
+    # Type-only model - no element declaration needed
 
     map_element :phone, to: :phone
   end
@@ -217,7 +218,7 @@ class Person < Lutaml::Model::Serializable
   end
 
   xml do
-    root "Person"
+    element "Person"
 
     map_element :email, to: :email
     map_element :phone, to: :phone

data/docs/_pages/index.adoc

@@ -22,6 +22,7 @@ Fundamental concepts, configuration, and essential features of Lutaml::Model.
 * link:breaking-changes[Breaking Changes] - Version compatibility
 * link:comparison-with-shale[Comparison with Shale] - Migration guide
 * link:xml-conformance[XML Standards Conformance] - W3C spec compliance status
+* link:../guides/opal[Opal Usage] - Run in the browser via Opal
 * link:troubleshooting[Troubleshooting] - Common issues and solutions
 
 == Getting started

data/docs/_pages/quick-start.adoc

@@ -56,7 +56,7 @@ class Person < Lutaml::Model::Serializable
   attribute :age, :integer
 
   xml do
-    root "person"
+    element "person"
     map_element "name", to: :name
     map_element "age", to: :age
   end

data/docs/_pages/serialization_adapters.adoc

@@ -192,8 +192,7 @@ Requires the `nokogiri` gem.
 Oga::
 (optional)
 Pure Ruby XML parser.
-Does not require native extensions and is suitable for
-https://opalrb.com[Opal] (Ruby on JavaScript).
+Does not require native extensions.
 Requires the `oga` gem.
 
 Ox::
@@ -206,6 +205,8 @@ REXML::
 (optional)
 Pure Ruby XML parser, bundled as a default gem with Ruby.
 Moved from standard library to a default gem in Ruby 3.0.
+Opal-compatible: Opal reimplements `strscan` and `stringio` in its stdlib,
+enabling REXML to compile cleanly to JavaScript.
 Requires the `rexml` gem (bundled with Ruby by default).
 
 

data/docs/_pages/value_types.adoc

@@ -92,7 +92,7 @@ class Event < Lutaml::Model::Serializable
   attribute :start_date, :date
 
   xml do
-    root "event"
+    element "event"
     map_element "startDate", to: :start_date
   end
 
@@ -150,7 +150,7 @@ class ProcessingTask < Lutaml::Model::Serializable
   attribute :processing_time, :duration
 
   xml do
-    root "task"
+    element "task"
     map_element "processingTime", to: :processing_time
   end
 end
@@ -180,7 +180,7 @@ class Resource < Lutaml::Model::Serializable
   attribute :schema_location, :uri
 
   xml do
-    root "resource"
+    element "resource"
     map_element "homepage", to: :homepage
     map_attribute "schemaLocation", to: :schema_location
   end
@@ -215,7 +215,7 @@ class Reference < Lutaml::Model::Serializable
   attribute :target, :qname
 
   xml do
-    root "reference"
+    element "reference"
     map_attribute "type", to: :ref_type
     map_element "target", to: :target
   end
@@ -253,7 +253,7 @@ class Attachment < Lutaml::Model::Serializable
   attribute :filename, :string
 
   xml do
-    root "attachment"
+    element "attachment"
     map_element "content", to: :content
     map_attribute "filename", to: :filename
   end
@@ -294,7 +294,7 @@ class Checksum < Lutaml::Model::Serializable
   attribute :algorithm, :string
 
   xml do
-    root "checksum"
+    element "checksum"
     map_element "value", to: :hash_value
     map_attribute "algorithm", to: :algorithm
   end
@@ -360,7 +360,7 @@ class Article < Lutaml::Model::Serializable
   attribute :title, :string
 
   xml do
-    root "article"
+    element "article"
     map_attribute "lang", to: :lang
     map_attribute "space", to: :space
     map_attribute "id", to: :id
@@ -486,7 +486,7 @@ class Task < Lutaml::Model::Serializable
   attribute :priority, :symbol
 
   xml do
-    root "task"
+    element "task"
     map_element "status", to: :status
     map_element "priority", to: :priority
   end
@@ -731,7 +731,7 @@ class Address < Lutaml::Model::Serializable
 
   # Define how this complex object maps to different formats
   xml do
-    root "Address"
+    element "Address"
     map_element "Street", to: :street
     map_element "City", to: :city
     map_element "PostalCode", to: :postal_code
@@ -1051,7 +1051,7 @@ end
 class Ceramic < Lutaml::Model::Serializable
   attribute :kiln_firing_time, HighPrecisionDateTime
   xml do
-    root 'ceramic'
+    element "ceramic"
     map_element 'kilnFiringTime', to: :kiln_firing_time
     # ...
   end

data/docs/_references/custom_registers.adoc

@@ -449,7 +449,7 @@ module Mml
     attribute :mrow, Mrow
 
     xml do
-      root "math"
+      element "math"
     end
   end
 end
@@ -545,7 +545,7 @@ class MyDocument < Lutaml::Model::Serializable
   attribute :math, Mml::V2::Math  # Has lutaml_default_register = :mml_v2
 
   xml do
-    root "document"
+    element "document"
     map_element "math", to: :math
   end
 end
@@ -639,7 +639,7 @@ module Mml
     attribute :mi_value, :string
 
     xml do
-      root "mmultiscripts"
+      element "mmultiscripts"
       map_element "mi", to: :mi_value
     end
   end
@@ -648,7 +648,7 @@ module Mml
     attribute :mmultiscripts_value, Mmultiscripts, collection: true
 
     xml do
-      root "math"
+      element "math"
       map_element "mmultiscripts", to: :mmultiscripts_value
     end
   end
@@ -665,7 +665,7 @@ class MyDocument < Lutaml::Model::Serializable
   attribute :math, Mml::Math
 
   xml do
-    root "document"
+    element "document"
     map_attribute "id", to: :id
     map_element "math", to: :math
   end
@@ -704,7 +704,7 @@ class MyDocument < Lutaml::Model::Serializable
   attribute :math, Mml::V2::Math  # Has lutaml_default_register = :mml_v2
 
   xml do
-    root "document"
+    element "document"
     map_element "math", to: :math
   end
 end
@@ -776,7 +776,7 @@ class Article < Lutaml::Model::Serializable
   attribute :formula, Mml::V2::Math
 
   xml do
-    root "article"
+    element "article"
     map_element "math", to: :formula
   end
 end