lutaml-model 0.8.12 → 0.8.13

data/docs/_guides/xml-mapping.adoc

@@ -174,7 +174,8 @@ class Paragraph < Lutaml::Model::Serializable
   attribute :italic, :string
 
   xml do
-    root 'p', mixed: true  # DEPRECATED - use mixed_content method instead
+    element 'p'
+    mixed_content  # DEPRECATED - use mixed_content method instead
     map_element 'bold', to: :bold
     map_element 'i', to: :italic
   end
@@ -206,19 +207,22 @@ end
 
 NOTE: Type-only models can only be parsed when embedded in parent models, not
 standalone. Attempting to call `Address.from_xml(xml)` will raise
-`NoRootMappingError`.
+`TypeOnlyMappingError`.
 
 // TODO: This understanding is wrong -- a type can declare attributes,
 // we need to fix this.
 
-The `no_root` method is deprecated.
-
-Syntax:
+The modern pattern is to omit the `element` declaration entirely for
+type-only models. The `no_root` method is deprecated.
 
+.Syntax for type-only models (modern pattern)
 [source,ruby]
 ----
-xml do
-  no_root
+class Address < Lutaml::Model::Serializable
+  xml do
+    # No element declaration - type-only model
+    map_element 'street', to: :street
+  end
 end
 ----
 
@@ -227,14 +231,14 @@ end
 ----
 class Address < Lutaml::Model::Serializable
   xml do
-    no_root  # DEPRECATED
+    no_root  # DEPRECATED - omit element declaration instead
     map_element 'street', to: :street
   end
 end
 ----
 
-When `no_root` is used, only `map_element` can be used because without a root
-element there cannot be attributes.
+When a model has no element declaration, only `map_element` can be used
+because without a root element there cannot be attributes.
 
 [example]
 ====
@@ -245,7 +249,7 @@ class NameAndCode < Lutaml::Model::Serializable
   attribute :code, :string
 
   xml do
-    no_root
+    # Type-only model - no element declaration needed
     map_element "code", to: :code
     map_element "name", to: :name
   end
@@ -450,7 +454,8 @@ To specify mixed content, the `mixed: true` option needs to be set at the
 [source,ruby]
 ----
 xml do
-  root 'xml_element_name', mixed: true
+  element 'xml_element_name'
+  mixed_content
 end
 ----
 
@@ -464,7 +469,8 @@ class Paragraph < Lutaml::Model::Serializable
   attribute :italic, :string
 
   xml do
-    root 'p', mixed: true
+    element 'p'
+    mixed_content
 
     map_element 'bold', to: :bold
     map_element 'i', to: :italic
@@ -655,7 +661,7 @@ class Example < Lutaml::Model::Serializable
   attribute :name, :string
 
   xml do
-    root 'example'
+    element "example"
     map_element 'name', to: :name
   end
 end
@@ -687,7 +693,7 @@ class RecordDate < Lutaml::Model::Serializable
   attribute :content, :string
 
   xml do
-    root "recordDate"
+    element "recordDate"
     map_content to: :content
   end
 end
@@ -696,7 +702,7 @@ class OriginInfo < Lutaml::Model::Serializable
   attribute :date_issued, RecordDate, collection: true
 
   xml do
-    root "originInfo"
+    element "originInfo"
     map_element "dateIssued", to: :date_issued
   end
 end
@@ -867,7 +873,7 @@ class Example < Lutaml::Model::Serializable
   attribute :value, :integer
 
   xml do
-    root 'example'
+    element "example"
     map_attribute 'value', to: :value
   end
 end
@@ -910,7 +916,7 @@ class Attribute < Lutaml::Model::Serializable
   attribute :value, TechXmiIntegerType
 
   xml do
-    root 'example'
+    element "example"
     map_attribute 'value', to: :value
   end
 end
@@ -1070,7 +1076,7 @@ class Example < Lutaml::Model::Serializable
   attribute :description, :string
 
   xml do
-    root 'example'
+    element "example"
     map_content to: :description
   end
 end
@@ -1213,7 +1219,7 @@ class Example < Lutaml::Model::Serializable
   attribute :note, :string
 
   xml do
-    root 'example'
+    element "example"
     map_element :name, to: :name, cdata: true
     map_content to: :description, cdata: true
     map_element :title, to: :title, cdata: false
@@ -1260,7 +1266,7 @@ changes.
 [source,ruby]
 ----
 xml do
-  root "rfc"
+  element "rfc"
   map_element "title", to: :title
   map_processing_instruction "rfc", to: :pi_settings
 end
@@ -1293,7 +1299,7 @@ to different attributes:
 [source,ruby]
 ----
 xml do
-  root "doc"
+  element "doc"
   map_processing_instruction "rfc", to: :rfc_pis
   map_processing_instruction "xml-stylesheet", to: :stylesheet_pis
 end
@@ -1309,7 +1315,7 @@ content string is stored as-is:
 attribute :rfc_pis, :string, collection: true
 
 xml do
-  root "rfc"
+  element "rfc"
   map_processing_instruction "rfc", to: :rfc_pis
 end
 ----
@@ -1341,7 +1347,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
@@ -1465,7 +1471,7 @@ class Contact < Lutaml::Model::Serializable
   attribute :email, EmailType
 
   xml do
-    root 'contact'
+    element "contact"
     map_element 'email', to: :email  # Uses EmailNamespace automatically
   end
 end
@@ -1553,7 +1559,7 @@ class Properties < Lutaml::Model::Serializable
   attribute :template, :string
 
   xml do
-    root "Properties"
+    element "Properties"
     namespace AppNamespace
     map_element "Template", to: :template
   end

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

@@ -305,7 +305,7 @@ class Parent < Lutaml::Model::Serializable
 
   xml do
     namespace MyNamespace
-    root "parent"
+    element "parent"
     map_element "child", to: :value
   end
 end
@@ -340,7 +340,7 @@ class Parent < Lutaml::Model::Serializable
 
   xml do
     namespace MyNamespace
-    root "parent"
+    element "parent"
     map_element "child", to: :value
   end
 end
@@ -480,7 +480,7 @@ class Child < Lutaml::Model::Serializable
   attribute :value, :string
   xml do
     namespace NS
-    root "child"
+    element "child"
     map_element "value", to: :value
   end
 end
@@ -489,7 +489,7 @@ class Parent < Lutaml::Model::Serializable
   attribute :child, Child
   xml do
     namespace NS
-    root "parent"
+    element "parent"
     map_element "child", to: :child
   end
 end

data/docs/_guides/xml-namespaces.adoc

@@ -483,7 +483,7 @@ class Document < Lutaml::Model::Serializable
   attribute :content, :string
 
   xml do
-    root "doc"
+    element "doc"
     map_attribute "lang", to: :lang
     map_attribute "space", to: :space
     map_content to: :content
@@ -761,7 +761,7 @@ class Article < Lutaml::Model::Serializable
   attribute :content, :string
 
   xml do
-    root "article"
+    element "article"
     map_attribute "lang", to: :lang
     map_attribute "space", to: :space
     map_attribute "id", to: :id

data/docs/_guides/xml_mappings/04_xml_namespace_class.adoc

@@ -430,7 +430,7 @@ class ProcessingTask < Lutaml::Model::Serializable
   attribute :processing_time, :duration
 
   xml do
-    root "task"
+    element "task"
     map_element "processingTime", to: :processing_time
   end
 end
@@ -465,7 +465,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
@@ -500,7 +500,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
@@ -538,7 +538,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
@@ -579,7 +579,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
@@ -710,7 +710,7 @@ class Contact < Lutaml::Model::Serializable
   attribute :email, EmailType
 
   xml do
-    root 'contact'
+    element "contact"
     map_element 'email', to: :email  # Uses EmailNamespace automatically
   end
 end
@@ -744,7 +744,7 @@ class CustomModel < Lutaml::Model::Serializable
   attribute :value, :string
 
   xml do
-    root 'customElement'
+    element "customElement"
     map_element 'value', to: :value
   end
 end
@@ -789,7 +789,7 @@ class Document < Lutaml::Model::Serializable
   attribute :content, :string  # Regular attribute, no type namespace
 
   xml do
-    root 'document'
+    element "document"
 
     map_element 'title', to: :title      # Becomes <dc:title> from Type
     map_element 'creator', to: :creator  # Becomes <dc:creator> from Type
@@ -953,7 +953,7 @@ class DctermsCreatedType < Lutaml::Model::Serializable
   attribute :type, XsiTypeType
 
   xml do
-    root 'created'
+    element "created"
     # This becomes xsi:type from XsiTypeType
     map_attribute 'type', to: :type
     map_content to: :value
@@ -967,7 +967,7 @@ class DctermsModifiedType < Lutaml::Model::Serializable
   attribute :type, XsiTypeType
 
   xml do
-    root 'modified'
+    element "modified"
     map_attribute 'type', to: :type
     map_content to: :value
   end
@@ -985,7 +985,7 @@ class CoreProperties < Lutaml::Model::Serializable
   attribute :modified, DctermsModifiedType
 
   xml do
-    root 'coreProperties'
+    element "coreProperties"
 
     # Type namespaces automatically applied
     map_element 'title', to: :title              # Becomes <dc:title>
@@ -1078,7 +1078,7 @@ class Model < Lutaml::Model::Serializable
   attribute :value, DefaultType
 
   xml do
-    root 'model'
+    element "model"
 
     # Case 1: Type namespace used (no explicit namespace)
     map_element 'value1', to: :value
@@ -1119,7 +1119,7 @@ class Product < Lutaml::Model::Serializable
   attribute :schema_type, XsiTypeType
 
   xml do
-    root 'product'
+    element "product"
     map_attribute 'id', to: :id              # Unqualified: id="..."
     map_attribute 'type', to: :schema_type   # Qualified: xsi:type="..."
   end
@@ -1371,7 +1371,7 @@ class Document < Lutaml::Model::Serializable
   attribute :creator, DcCreatorType
 
   xml do
-    root 'document'
+    element "document"
     map_element 'title', to: :title
     map_element 'creator', to: :creator
   end
@@ -1401,7 +1401,7 @@ class Document < Lutaml::Model::Serializable
   attribute :creator, DcCreatorType
 
   xml do
-    root 'document'
+    element "document"
     map_element 'title', to: :title
     map_element 'creator', to: :creator
   end
@@ -1530,7 +1530,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :title, DcTitleType
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
     namespace_scope [VcardNamespace, DcNamespace]  <1>
 
@@ -1612,7 +1612,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
     namespace_scope [VcardNamespace, DcNamespace, DctermsNamespace]  <1>
 
@@ -1676,7 +1676,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
     namespace_scope [VcardNamespace, DcNamespace]  <1>
 

data/docs/_guides/xml_mappings/05_common_patterns.adoc

@@ -21,7 +21,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
@@ -58,7 +58,7 @@ class Glaze < Lutaml::Model::Serializable
   attribute :temperature, :integer
 
   xml do
-    root 'Glaze'
+    element "Glaze"
     map_element 'color', to: :color
     map_element 'temperature', to: :temperature
   end
@@ -69,7 +69,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :glaze, Glaze
 
   xml do
-    root 'Ceramic'
+    element "Ceramic"
     map_element 'Type', to: :type
     map_element 'Glaze', to: :glaze
   end
@@ -102,7 +102,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :glaze, :string
 
   xml do
-    root 'Ceramic'
+    element "Ceramic"
     namespace 'http://example.com/ceramic'
     map_element 'Type', to: :type
     map_element 'Glaze', to: :glaze
@@ -131,7 +131,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :glaze, :string
 
   xml do
-    root 'Ceramic'
+    element "Ceramic"
     namespace 'http://example.com/ceramic', 'cer'
     map_element 'Type', to: :type
     map_element 'Glaze', to: :glaze
@@ -1146,7 +1146,7 @@ class Example < Lutaml::Model::Serializable
   attribute :note, :string
 
   xml do
-    root 'example'
+    element "example"
     map_element :name, to: :name, cdata: true
     map_content to: :description, cdata: true
     map_element :title, to: :title, cdata: false
@@ -1327,7 +1327,7 @@ class CeramicCollection < Lutaml::Model::Serializable
   attribute :items, Ceramic, collection: true
 
   xml do
-    root 'ceramics'
+    element "ceramics"
     map_element 'ceramic', to: :items
   end
 end
@@ -1354,7 +1354,7 @@ class TitleCollection < Lutaml::Model::Collection
   instances :items, :string
 
   xml do
-    root "titles"
+    element "titles"
     map_attribute "title", to: :items, delimiter: "; "
   end
 end
@@ -1387,7 +1387,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
@@ -1444,7 +1444,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
@@ -1457,7 +1457,7 @@ class Person < Lutaml::Model::Serializable
   import_model_attributes Address
 
   xml do
-    root "Person"
+    element "Person"
 
     map_element :name, to: :name
     sequence do
@@ -1617,14 +1617,14 @@ end
 # Use in document model
 class Document < Lutaml::Model::Serializable
   namespace DocumentNamespace
-  
+
   attribute :title, DcTitleType
   attribute :creator, DcCreatorType
   attribute :content, :string
 
   xml do
-    root 'document'
-    
+    element "document"
+
     map_element 'title', to: :title      # Uses DublinCoreNamespace
     map_element 'creator', to: :creator  # Uses DublinCoreNamespace
     map_element 'content', to: :content  # No type namespace
@@ -1704,7 +1704,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace_scope [VcardNamespace, DcNamespace, DctermsNamespace]  <1>
 
     map_element "version", to: :version
@@ -1764,7 +1764,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :color, :string
 
   xml do
-    root 'Ceramic'
+    element "Ceramic"
     namespace CeramicNamespace
     map_element 'Type', to: :type  # Inherits parent namespace (qualified)
     map_element 'Glaze', to: :glaze

data/docs/_guides/xml_mappings/06_migration_guide.adoc

@@ -147,7 +147,7 @@ For models with complex namespace requirements:
 
 Replace `root()` with `element()` for clarity:
 
-1. Change `root 'element-name'` to `element 'element-name'`
+1. Change `element "element-name"` to `element 'element-name'`
 2. Move `mixed: true` to use `mixed_content` method
 3. Move `ordered: true` to use `ordered` method
 
@@ -476,7 +476,7 @@ end
 class DcTitleType < Lutaml::Model::Type::String
   namespace DublinCoreNamespace  # ⚠️ DEPRECATED
   xsd_type 'titleType'
-  
+
   def self.cast(value)
     super(value)
   end
@@ -484,7 +484,7 @@ end
 
 class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType
-  
+
   xml do
     root 'document'
     map_element 'title', to: :title
@@ -503,7 +503,7 @@ end
 class DcTitleType < Lutaml::Model::Type::String
   xml_namespace DublinCoreNamespace  # ✅ CURRENT
   xsd_type 'titleType'
-  
+
   def self.cast(value)
     super(value)
   end
@@ -511,7 +511,7 @@ end
 
 class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType
-  
+
   xml do
     root 'document'
     map_element 'title', to: :title

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