lutaml-model 0.8.12 → 0.8.13

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

data/docs/_references/format-independent-features.adoc

@@ -126,7 +126,7 @@ class Ceramic < Lutaml::Model::Serializable
 
   # Mapping-level transformation in XML format
   xml do
-    root "Ceramic"
+    element "Ceramic"
     map_attribute "glaze-type", to: :glaze_type, transform: {
       export: ->(value) { "Traditional #{value}" },
       import: ->(value) { value.gsub("Traditional ", "") }
@@ -234,7 +234,7 @@ class Ceramic < Lutaml::Model::Serializable
 
   # Mapping-level transformation in XML format
   xml do
-    root "Ceramic"
+    element "Ceramic"
     map_attribute "glaze-type", to: :glaze_type, transform: {
       export: ->(value) { "Traditional #{value}" },
       import: ->(value) { value.gsub("Traditional ", "") }
@@ -454,7 +454,7 @@ class CombinedTransformModel < Lutaml::Model::Serializable
   end
 
   xml do
-    root "CombinedTransformModel"
+    element "CombinedTransformModel"
     map_element "title", to: :title, transform: SuffixTransformer
   end
 end
@@ -662,7 +662,7 @@ class Glaze < Lutaml::Model::Serializable
   attribute :firing_time, :integer, default: -> { 60 }
 
   xml do
-    root "glaze"
+    element "glaze"
     map_element 'color', to: :color
     map_element 'opacity', to: :opacity, render_default: true
     map_attribute 'temperature', to: :temperature

data/docs/_references/instance-serialization.adoc

@@ -31,7 +31,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/_references/parent-root-context.adoc

@@ -34,7 +34,7 @@ class Tag < Lutaml::Model::Serializable
   attribute :text, :string
 
   xml do
-    root "Tag"
+    element "Tag"
 
     map_content to: :text
   end
@@ -48,7 +48,7 @@ class Tags < Lutaml::Model::Serializable
   attribute :tag, Tag, collection: true
 
   xml do
-    root "Tags"
+    element "Tags"
 
     map_element "Tag", to: :tag
   end
@@ -62,7 +62,7 @@ class Post < Lutaml::Model::Serializable
   attribute :tags, Tags, collection: true
 
   xml do
-    root "Post"
+    element "Post"
     map_element "Tags", to: :tags
   end
 

data/docs/_tutorials/basic-model-definition.adoc

@@ -121,7 +121,7 @@ class Kiln < Lutaml::Model::Serializable
   attribute :temperature, :integer
 
   xml do
-    root 'kiln'
+    element "kiln"
     map_element 'brand', to: :brand
     map_element 'capacity', to: :capacity
     map_element 'temperature', to: :temperature

data/docs/_tutorials/first-xml-serialization.adoc

@@ -74,7 +74,7 @@ class Example < Lutaml::Model::Serializable
   attribute :name, :string
 
   xml do
-    root 'example'
+    element "example"
     map_element 'name', to: :name
   end
 end
@@ -116,7 +116,7 @@ class Example < Lutaml::Model::Serializable
   attribute :value, :integer
 
   xml do
-    root 'example'
+    element "example"
     map_attribute 'value', to: :value
   end
 end
@@ -158,7 +158,7 @@ class Example < Lutaml::Model::Serializable
   attribute :description, :string
 
   xml do
-    root 'example'
+    element "example"
     map_content to: :description
   end
 end
@@ -192,7 +192,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :temperature, :integer
 
   xml do
-    root 'ceramic'
+    element "ceramic"
     map_element 'name', to: :name
     map_attribute 'temperature', to: :temperature
     map_content to: :description

data/docs/_tutorials/lutaml-xml-architecture.adoc

@@ -576,7 +576,7 @@ end
 ```ruby
 class PurchaseOrder < Lutaml::Model::Serializable
   xml do
-    root "purchaseOrder"                    # Root element name
+    element "purchaseOrder"                    # Root element name
     namespace PoNamespace                    # Model namespace
 
     map_element "shipTo", to: :ship_to       # Map element
@@ -654,7 +654,7 @@ class Book < Lutaml::Model::Serializable
   attribute :author, Person
 
   xml do
-    root "Book"
+    element "Book"
     namespace BookNamespace
     map_element "title", to: :title
     map_element "author", to: :author
@@ -979,7 +979,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :comment, :string
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
     map_element "comment", to: :comment
   end
@@ -1062,7 +1062,7 @@ class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType
 
   xml do
-    root "document"
+    element "document"
     map_element "title", to: :title
   end
 end

data/docs/_tutorials/validation-basics.adoc

@@ -152,7 +152,7 @@ class Contact < Lutaml::Model::Serializable
   end
 
   xml do
-    root "contact"
+    element "contact"
     map_element "email", to: :email
     map_element "phone", to: :phone
   end

data/docs/_tutorials/working-with-collections.adoc

@@ -39,7 +39,7 @@ class Studio < Lutaml::Model::Serializable
   attribute :potters, :string, collection: true
 
   xml do
-    root 'studio'
+    element "studio"
     map_element 'name', to: :name
     map_element 'potter', to: :potters
   end
@@ -142,7 +142,7 @@ class PotterCollection < Lutaml::Model::Collection
   instances :potters, Potter
 
   json do
-    root "potters"
+    key "potters"
     map_instances to: :potters
   end
 end