lutaml-model 0.8.12 → 0.8.13

data/docs/_tutorials/xml-namespaces-basics.adoc

@@ -70,7 +70,7 @@ class Ceramic < Lutaml::Model::Serializable
   attribute :glaze, :string
 
   xml do
-    root 'Ceramic'
+    element "Ceramic"
     namespace CeramicNamespace
 
     map_element 'Type', to: :type

data/docs/_tutorials/xml-schema-primer-style-guide.adoc

@@ -46,7 +46,7 @@ class UsAddress < Lutaml::Model::Serializable
   attribute :zip, :decimal
 
   xml do
-    root "USAddress"
+    element "USAddress"
     map_element "name", to: :name
     map_element "street", to: :street
     map_element "city", to: :city
@@ -81,7 +81,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :comment, :string
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     map_element "shipTo", to: :ship_to
     map_element "billTo", to: :bill_to
     map_element "comment", to: :comment
@@ -123,7 +123,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :ship_to, UsAddress
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     map_attribute "orderDate", to: :order_date
     map_element "shipTo", to: :ship_to
   end
@@ -157,7 +157,7 @@ class Item < Lutaml::Model::Serializable
   attribute :us_price, :decimal
 
   xml do
-    root "Item"
+    element "Item"
     map_element "productName", to: :product_name
     map_element "quantity", to: :quantity
     map_element "USPrice", to: :us_price
@@ -168,7 +168,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :items, Item, collection: true
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     map_element "items", to: :items
   end
 end
@@ -239,7 +239,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :bill_to, UsAddress
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
 
     map_element "shipTo", to: :ship_to
@@ -288,7 +288,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :ship_to, UsAddress
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
 
     map_element "shipTo", to: :ship_to
@@ -350,7 +350,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :order_date, :string
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
 
     map_attribute "orderDate", to: :order_date
@@ -418,7 +418,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :comment, :string  # This one will be unqualified
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
 
     map_element "shipTo", to: :ship_to
@@ -489,7 +489,7 @@ class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType  # Automatically uses DcNamespace
 
   xml do
-    root "document"
+    element "document"
     map_element "title", to: :title
   end
 end
@@ -542,7 +542,7 @@ class Metadata < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "metadata"
+    element "metadata"
     map_element "title", to: :title
     map_element "created", to: :created
   end
@@ -586,7 +586,7 @@ class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType
 
   xml do
-    root "document"
+    element "document"
     namespace ModelNamespace  # Model namespace
     map_element "title", to: :title  # Uses Type namespace (DcNamespace)
   end
@@ -620,7 +620,7 @@ class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType
 
   xml do
-    root "document"
+    element "document"
     map_element "title", to: :title, namespace: OverrideNamespace
   end
 end
@@ -659,7 +659,7 @@ class Document < Lutaml::Model::Serializable
   attribute :schema_type, XsiTypeType
 
   xml do
-    root "document"
+    element "document"
     map_attribute "name", to: :name
     map_attribute "type", to: :schema_type
   end
@@ -701,7 +701,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :ship_to, UsAddress
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
     map_element "shipTo", to: :ship_to
   end
@@ -749,7 +749,7 @@ The `namespace_scope` directive consolidates multiple namespace declarations at
 ----
 class Document < Lutaml::Model::Serializable
   xml do
-    root "document"
+    element "document"
     namespace RootNamespace
 
     # Hoist multiple namespaces to root
@@ -794,7 +794,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :title, DcTitleType
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     # Hoist DcNamespace to root
@@ -882,7 +882,7 @@ class Address < Lutaml::Model::Serializable
   attribute :city, :string
 
   xml do
-    root "Address"
+    element "Address"
     map_element "street", to: :street
     map_element "city", to: :city
   end
@@ -893,7 +893,7 @@ class Person < Lutaml::Model::Serializable
   attribute :address, Address
 
   xml do
-    root "Person"
+    element "Person"
     map_element "name", to: :name
     map_element "address", to: :address
   end
@@ -934,7 +934,7 @@ class Person < Lutaml::Model::Serializable
   attribute :work_address, AddressType
 
   xml do
-    root "Person"
+    element "Person"
     map_element "homeAddress", to: :home_address
     map_element "workAddress", to: :work_address
   end
@@ -975,7 +975,7 @@ class Item < Lutaml::Model::Serializable
   attribute :price, Price
 
   xml do
-    root "Item"
+    element "Item"
     map_element "name", to: :name
     map_attribute "price", to: :price
   end
@@ -1017,7 +1017,7 @@ class Product < Lutaml::Model::Serializable
   attribute :release_date, :date
 
   xml do
-    root "Product"
+    element "Product"
     map_element "name", to: :name
     map_element "price", to: :price
     map_element "quantity", to: :quantity
@@ -1055,7 +1055,7 @@ class Item < Lutaml::Model::Serializable
   attribute :price, UsPriceType
 
   xml do
-    root "Item"
+    element "Item"
     map_element "USPrice", to: :price
   end
 end
@@ -1106,7 +1106,7 @@ class Address < Lutaml::Model::Serializable
   attribute :city, :string
 
   xml do
-    root "Address"
+    element "Address"
     map_element "name", to: :name
     map_element "street", to: :street
     map_element "city", to: :city
@@ -1118,7 +1118,7 @@ class InternationalAddress < Address
   attribute :country, :string
 
   xml do
-    root "InternationalAddress"
+    element "InternationalAddress"
     map_element *Address.mappings  # Inherit mappings
     map_element "country", to: :country
   end
@@ -1140,7 +1140,7 @@ class Shipment < Lutaml::Model::Serializable
   attribute :address, Address
 
   xml do
-    root "Shipment"
+    element "Shipment"
     namespace_scope [XsiNamespace]
     map_element "address", to: :address
   end
@@ -1231,7 +1231,7 @@ class UsAddress < Lutaml::Model::Serializable
   attribute :zip, :decimal
 
   xml do
-    root "USAddress"
+    element "USAddress"
     map_element "name", to: :name
     map_element "street", to: :street
     map_element "city", to: :city
@@ -1247,7 +1247,7 @@ class Item < Lutaml::Model::Serializable
   attribute :comment, :string
 
   xml do
-    root "Item"
+    element "Item"
     map_element "productName", to: :product_name
     map_element "quantity", to: :quantity
     map_element "USPrice", to: :us_price
@@ -1264,7 +1264,7 @@ class PurchaseOrder < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "purchaseOrder"
+    element "purchaseOrder"
     namespace PoNamespace
 
     namespace_scope [

data/docs/cli_compare.adoc

@@ -69,7 +69,7 @@ class TermiumExtract < Lutaml::Model::Serializable
   attribute :extract_language, ExtractLanguage, collection: true
 
   xml do
-    root "termium_extract"
+    element "termium_extract"
     namespace "http://termium.tpsgc-pwgsc.gc.ca/schemas/2012/06/Termium", "ns2"
 
     map_attribute "language", to: :language

data/docs/index.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/namespace-management.adoc

@@ -110,10 +110,10 @@ IMPORTANT: `namespace_scope` grants **ELIGIBILITY** to hoist namespaces to the r
 ----
 xml do
   namespace RootNamespace
-  
+
   # Simple list (all use :auto mode)
   namespace_scope [Namespace1, Namespace2, Namespace3]
-  
+
   # Per-namespace control with hash format
   namespace_scope [
     { namespace: Namespace1, declare: :always },
@@ -169,7 +169,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :email, :string
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     map_element "version", to: :version
@@ -244,7 +244,7 @@ class Contact < Lutaml::Model::Serializable
   attribute :note, DcTitleType
 
   xml do
-    root "contact"
+    element "contact"
 
     map_element "title", to: :title
     map_element "note", to: :note
@@ -255,7 +255,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :contact, Contact
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     map_element "contact", to: :contact
@@ -300,7 +300,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :contact, Contact
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     # Hoist DcNamespace to root
@@ -395,7 +395,7 @@ class Metadata < Lutaml::Model::Serializable
   attribute :format, XsiTypeType
 
   xml do
-    root "metadata"
+    element "metadata"
 
     map_element "title", to: :title
     map_element "creator", to: :creator
@@ -411,7 +411,7 @@ class Vcard < Lutaml::Model::Serializable
   attribute :metadata, Metadata
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     # Consolidate all namespaces at root
@@ -483,7 +483,7 @@ class Vcard < Lutaml::Model::Serializable
   # No DcTitleType attributes used
 
   xml do
-    root "vCard"
+    element "vCard"
     namespace VcardNamespace
 
     # Try to hoist unused DcNamespace
@@ -630,7 +630,7 @@ class Parent < Lutaml::Model::Serializable
   attribute :child_value, :string
 
   xml do
-    root "parent"
+    element "parent"
     namespace ParentNamespace
 
     map_element "child", to: :child_value
@@ -826,7 +826,7 @@ class Document < Lutaml::Model::Serializable
   attribute :title, DcTitleType  # Automatically uses DcNamespace
 
   xml do
-    root "document"
+    element "document"
     namespace DocumentNamespace
 
     map_element "title", to: :title  # Becomes <dc:title>
@@ -845,7 +845,7 @@ Simplest case—all elements in one namespace:
 ----
 class Document < Lutaml::Model::Serializable
   xml do
-    root "document"
+    element "document"
     namespace DocumentNamespace
     # No namespace_scope needed
   end
@@ -863,7 +863,7 @@ class Document < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType  # DctermsNamespace
 
   xml do
-    root "document"
+    element "document"
     namespace DocumentNamespace
     # No namespace_scope - Type namespaces hoist locally
   end
@@ -881,7 +881,7 @@ class Document < Lutaml::Model::Serializable
   attribute :created, DctermsCreatedType
 
   xml do
-    root "document"
+    element "document"
     namespace DocumentNamespace
 
     # Hoist all Type namespaces to root

data/lib/lutaml/key_value/mapping.rb

@@ -21,20 +21,45 @@ module Lutaml
         @finalized
       end
 
+      # Set the wrapper key for key-value serialization (JSON, YAML, TOML).
+      #
+      # When set, serialized output wraps all instances under this key
+      # (e.g., `key "items"` produces `{"items": [...]}`).
+      # When not called (or called with nil), instances are serialized directly
+      # at the top level (e.g., `[...]`).
+      #
+      # @param name [String, nil] the wrapper key name
+      def key(name = nil)
+        @key = name
+      end
+
+      def key_name
+        @key
+      end
+
+      # @deprecated Use {#key} instead. In key-value formats, the wrapper is a key, not a root.
       def root(name = nil)
-        @root = name
+        @key = name
       end
 
+      # @deprecated Omit key call instead. Not calling key means no wrapper key.
       def no_root
-        @root = nil
+        @key = nil
+      end
+
+      # Returns true when no wrapper key is set (instances serialized at top level).
+      def no_key?
+        @key.nil?
       end
 
+      # @deprecated Use {#no_key?} instead.
       def no_root?
-        @root.nil?
+        no_key?
       end
 
+      # @deprecated Use {#key_name} instead.
       def root_name
-        @root
+        @key
       end
 
       def map(
@@ -104,7 +129,7 @@ module Lutaml
 
       def map_instances(to:, polymorphic: {})
         @instance = to
-        map(root_name || to, to: to, polymorphic: polymorphic)
+        map(key_name || to, to: to, polymorphic: polymorphic)
         map_to_instance
       end
 
@@ -125,7 +150,7 @@ module Lutaml
       def map_to_instance
         return if !instance_mapping?
 
-        mapping_name = name_for_mapping(nil, root_name || @instance)
+        mapping_name = name_for_mapping(nil, key_name || @instance)
         @mappings[mapping_name].child_mappings = @key_mapping.merge(@value_mapping)
       end
 

data/lib/lutaml/model/collection.rb

@@ -310,8 +310,8 @@ module Lutaml
         def to(format, instance, options = {})
           mappings = mappings_for(format)
 
-          if mappings.no_root? && collection_no_root_to?(format)
-            collection_no_root_to(format, mappings, instance, options)
+          if mappings.no_root? && collection_unwrapped_to?(format)
+            collection_unwrapped_to(format, mappings, instance, options)
           else
             super(format, instance, options.merge(collection: true))
           end
@@ -322,7 +322,7 @@ module Lutaml
           data = super
 
           if !collection_structured_format?(format) && mappings.no_root? && !mappings.root_mapping
-            unwrap_no_root_data(data)
+            unwrap_unwrapped_data(data)
           else
             data
           end
@@ -332,7 +332,7 @@ module Lutaml
           mappings = mappings_for(format)
 
           if collection_structured_format?(format) && mappings.no_root?
-            data = wrap_no_root_input(format, mappings, data)
+            data = wrap_unwrapped_input(format, mappings, data)
           end
 
           super(format, data, options.merge(from_collection: true))
@@ -355,21 +355,21 @@ module Lutaml
           false
         end
 
-        # Hook: returns true if this format handles no_root serialization specially.
+        # Hook: returns true if this format handles unwrapped serialization specially.
         # XML overrides to return true for :xml format.
-        def collection_no_root_to?(_format)
+        def collection_unwrapped_to?(_format)
           false
         end
 
-        # Hook for structured-format no_root serialization (e.g., XML).
+        # Hook for unwrapped serialization (e.g., XML).
         # XML overrides to serialize each mapping separately.
-        def collection_no_root_to(_format, _mappings, _instance, _options)
+        def collection_unwrapped_to(_format, _mappings, _instance, _options)
           raise NotImplementedError
         end
 
-        # Hook for structured-format no_root input wrapping (e.g., XML).
+        # Hook for wrapping unwrapped input (e.g., XML).
         # XML overrides to wrap raw data in a fake root tag.
-        def wrap_no_root_input(_format, _mappings, data)
+        def wrap_unwrapped_input(_format, _mappings, data)
           data
         end
 
@@ -379,7 +379,7 @@ module Lutaml
 
         private
 
-        def unwrap_no_root_data(data)
+        def unwrap_unwrapped_data(data)
           # Convert KeyValueElement to Hash if needed
           hash = data.is_a?(Hash) ? data : data.to_hash
           # Handle "__root__" wrapper for key-value formats (created by transformation)

data/lib/lutaml/model/error/no_root_mapping_error.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "type_only_mapping_error"
+
 module Lutaml
   module Model
-    class NoRootMappingError < Error
-      def initialize(model)
-        super("#{model} has `no_root`, it allowed only for reusable models")
-      end
-    end
+    # @deprecated Use {TypeOnlyMappingError} instead.
+    NoRootMappingError = TypeOnlyMappingError
   end
 end

data/lib/lutaml/model/error/no_root_namespace_error.rb

@@ -1,9 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "type_only_namespace_error"
+
 module Lutaml
   module Model
-    class NoRootNamespaceError < Error
-      def to_s
-        "Cannot assign namespace to `no_root`"
-      end
-    end
+    # @deprecated Use {TypeOnlyNamespaceError} instead.
+    NoRootNamespaceError = TypeOnlyNamespaceError
   end
 end

data/lib/lutaml/model/error/type_only_mapping_error.rb

@@ -0,0 +1,13 @@
+module Lutaml
+  module Model
+    class TypeOnlyMappingError < Error
+      def initialize(model)
+        super("#{model} is a type-only model (no element declared), " \
+              "it can only be used as an embedded type through a parent model.")
+      end
+    end
+
+    # @deprecated Use {TypeOnlyMappingError} instead.
+    NoRootMappingError = TypeOnlyMappingError
+  end
+end

data/lib/lutaml/model/error/type_only_namespace_error.rb

@@ -0,0 +1,12 @@
+module Lutaml
+  module Model
+    class TypeOnlyNamespaceError < Error
+      def to_s
+        "Cannot assign namespace to a type-only model (no element declared)."
+      end
+    end
+
+    # @deprecated Use {TypeOnlyNamespaceError} instead.
+    NoRootNamespaceError = TypeOnlyNamespaceError
+  end
+end

data/lib/lutaml/model/version.rb

@@ -2,6 +2,6 @@
 
 module Lutaml
   module Model
-    VERSION = "0.8.12"
+    VERSION = "0.8.13"
   end
 end

data/lib/lutaml/model.rb

@@ -149,6 +149,7 @@ module Lutaml
              "#{__dir__}/model/error/incorrect_sequence_error"
     autoload :ChoiceUpperBoundError,
              "#{__dir__}/model/error/choice_upper_bound_error"
+    autoload :TypeOnlyMappingError, "#{__dir__}/model/error/type_only_mapping_error"
     autoload :NoRootMappingError, "#{__dir__}/model/error/no_root_mapping_error"
     autoload :ImportModelWithRootError,
              "#{__dir__}/model/error/import_model_with_root_error"
@@ -160,6 +161,8 @@ module Lutaml
              "#{__dir__}/model/error/choice_lower_bound_error"
     autoload :NoMappingFoundError,
              "#{__dir__}/model/error/no_mapping_found_error"
+    autoload :TypeOnlyNamespaceError,
+             "#{__dir__}/model/error/type_only_namespace_error"
     autoload :NoRootNamespaceError,
              "#{__dir__}/model/error/no_root_namespace_error"
     autoload :PolymorphicError, "#{__dir__}/model/error/polymorphic_error"

data/lib/lutaml/xml/adapter/base_adapter.rb

@@ -1,14 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../document"
-require_relative "../declaration_handler"
-require_relative "../doctype_extractor"
-require_relative "../polymorphic_value_handler"
-require_relative "xml_parser"
-require_relative "xml_serializer"
-require_relative "plan_based_builder"
-require_relative "namespace_uri_collector"
-
 module Lutaml
   module Xml
     module Adapter

data/lib/lutaml/xml/adapter/nokogiri_adapter.rb

@@ -2,7 +2,6 @@
 
 require "moxml"
 require "moxml/adapter/nokogiri"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/oga_adapter.rb

@@ -2,7 +2,6 @@
 
 require "oga"
 require "moxml/adapter/oga"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/ox_adapter.rb

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "moxml/adapter/ox"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml

data/lib/lutaml/xml/adapter/rexml_adapter.rb

@@ -3,7 +3,6 @@
 require "rexml/document"
 require "moxml"
 require "moxml/adapter/rexml"
-require_relative "base_adapter"
 
 module Lutaml
   module Xml