lutaml-model 0.7.1 → 0.7.7

data/README.adoc

@@ -17,7 +17,7 @@ for:
 
 It provides simple, flexible and comprehensive mechanisms for defining
 information models with attributes and types, and the serialization of them
-to/from serialization formats including JSON, XML, YAML, and TOML.
+to/from serialization formats including Hash, JSON, XML, YAML, and TOML.
 
 For serialization formats, it uses an adapter pattern to support multiple
 libraries for each format, providing flexibility and extensibility for your data
@@ -33,12 +33,17 @@ Lutaml::Model are provided in <<migrate-from-shale>>.
 == Features
 
 * Define models with attributes and types
-* Serialize and deserialize models to/from JSON, XML, YAML, and TOML
+* Serialize and deserialize models to/from Hash, JSON, XML, YAML, and TOML
 * Support for multiple serialization libraries (e.g., `toml-rb`, `tomlib`)
 * Configurable adapters for different serialization formats
 * Support for collections and default values
 * Custom serialization/deserialization methods
 * XML namespaces and mappings
+* Generate serialization schemas from model definitions (<<schema-generation>>)
+* Import serialization schemas to define models (<<schema-import>>)
+* Create custom adapters for additional data formats (see <<custom-adapters>>)
+* Dynamically modify model attribute types using registers (see <<custom-registers>>)
+
 
 
 == Data modeling in a nutshell
@@ -269,10 +274,26 @@ Or install it yourself as:
 gem install lutaml-model
 ----
 
+
+== Components
+
+LutaML provides the following set of components to model information in a
+structured way.
+
+* <<model-definition,Basic models>>
+* <<attribute-definition,Attributes in models>>
+* <<value-definition,Values assigned to attributes>>
+* <<collection-definition,Collections of models>>
+
+
+[[model-definition]]
 == Model
 
 === General
 
+A LutaML model is used to represent a class of information, of which a model
+instance is a set of information representing a coherent concept.
+
 There are two ways to define an information model in Lutaml::Model:
 
 * Inheriting from the `Lutaml::Model::Serializable` class
@@ -376,7 +397,7 @@ same class and all their attributes are equal.
 > # true
 ----
 
-
+[[value-definition]]
 == Value types
 
 === General types
@@ -496,7 +517,7 @@ serialization format and returns the object to be assigned to the `Value` class'
 `to_{format}`:: Serializes the object to a string of the serialization format.
 
 The `{format}` part of the method name is the serialization format in lowercase
-(e.g. `json`, `xml`, `yaml`, `toml`).
+(e.g. `hash`, `json`, `xml`, `yaml`, `toml`).
 
 .Using custom serialization methods to handle a high-precision date-time type
 [example]
@@ -564,6 +585,7 @@ part lost due to the inability of JSON to handle high-precision date-time.
 ====
 
 
+[[attribute-definition]]
 == Attributes
 
 
@@ -615,6 +637,56 @@ puts s.established
 ----
 ====
 
+==== Restricting the value of an attribute
+
+The `restrict` class method is used to update or refine the validation rules for an attribute that has already been defined. This allows you to apply additional or stricter constraints to an existing attribute without redefining it.
+
+.Using the `restrict` class method to update the options of an existing attribute
+[example]
+====
+[source,ruby]
+----
+class Studio < Lutaml::Model::Serializable
+  attribute :name, :string
+  restrict :name, collection: 1..3, pattern: /[A-Za-z]+/
+end
+----
+====
+
+.Apply different restrictions to the existing attribute in multiple subclasses
+[example]
+====
+[source,ruby]
+----
+class Document < Lutaml::Model::Serializable
+  attribute :status, :string
+end
+
+class DraftDocument < Document
+  # Only allow "draft" or "in_review" as valid statuses for drafts
+  restrict :status, values: %w[draft in_review]
+end
+
+class PublishedDocument < Document
+  # Only allow "published" or "archived" as valid statuses for published documents
+  restrict :status, values: %w[published archived]
+end
+
+# Usage
+# Call .validate! to trigger validation and raise an error if the value is not allowed
+Document.new(status: "draft").validate!                # valid, there are no validation rules for `Document`
+Document.new(status: "published").validate!            # valid, there are no validation rules for `Document`
+DraftDocument.new(status: "draft").validate!           # valid
+DraftDocument.new(status: "in_review").validate!       # valid
+DraftDocument.new(status: "published").validate!       # raises error (not allowed)
+PublishedDocument.new(status: "published").validate!   # valid
+PublishedDocument.new(status: "archived").validate!    # valid
+PublishedDocument.new(status: "draft").validate!       # raises error (not allowed)
+----
+====
+
+All options that are supported by the `attribute` class method are also supported by the `restrict` method. Any unsupported option passed to `restrict` will result in a `Lutaml::Model::InvalidAttributeOptionsError` being raised.
+
 === Polymorphic attributes
 
 ==== General
@@ -820,7 +892,7 @@ end
 <1> The name of the polymorphic attribute.
 <2> The polymorphic superclass class.
 <3> Any options for the attribute.
-<4> The `polymorphic` option that determines the acceptable polymorphic subclasses.
+<4> The `polymorphic` option that determines the acceptable polymorphic subclasses, or just `true`.
 <5> The polymorphic subclasses.
 
 The `polymorphic` option is an array of polymorphic subclasses that the
@@ -863,6 +935,25 @@ end
 ----
 ====
 
+* If the attribute (collection or not) is meant to contain instances belonging
+to any polymorphic subclass of a defined base class, then set the `polymorphic:
+true` option.
++
+[example]
+====
+In the following code, `ReferenceSet` is a class that has a polymorphic
+attribute `references`. The `references` attribute can accept instances of
+any polymorphic subclass of the `Reference` base class, so `polymorphic: true`
+is set.
+
+[source,ruby]
+----
+class ReferenceSet < Lutaml::Model::Serializable
+  attribute :references, Reference, collection: true, polymorphic: true
+end
+----
+====
+
 * If the attribute (collection or not) is meant to contain instances belonging
 to more than one polymorphic subclass, then those acceptable polymorphic
 subclasses should be explicitly specified in the `polymorphic: [...]` option.
@@ -1051,16 +1142,16 @@ class Reference < Lutaml::Model::Serializable
 
   xml do
     map_attribute "reference-type", to: :_class, polymorphic_map: {
-      "document-ref" => "PolymorphicSpec::Base::DocumentReference",
-      "anchor-ref" => "PolymorphicSpec::Base::AnchorReference",
+      "document-ref" => "DocumentReference",
+      "anchor-ref" => "AnchorReference",
     }
     map_element "name", to: :name
   end
 
   key_value do
     map "_class", to: :_class, polymorphic_map: {
-      "Document" => "PolymorphicSpec::Base::DocumentReference",
-      "Anchor" => "PolymorphicSpec::Base::AnchorReference",
+      "Document" => "DocumentReference",
+      "Anchor" => "AnchorReference",
     }
     map "name", to: :name
   end
@@ -1484,9 +1575,13 @@ puts SomeModel.new.to_yaml
 ----
 ====
 
+
 === Derived attributes
 
-A derived attribute is computed dynamically based on an instance method instead of storing a static value. It is defined using the `method:` option.
+A derived attribute has a value computed dynamically on evaluation of an
+instance method.
+
+It is defined using the `method:` option.
 
 Syntax:
 
@@ -1572,6 +1667,7 @@ attributes.
 * The last attribute `completeName` is optional.
 ====
 
+NOTE: The `choice` directive can be used with `import_model_attributes`. For more details, see <<import-model-attributes-inside-choice, Using import_model_attributes inside a choice block>>.
 
 
 === Importable models for reuse
@@ -1628,6 +1724,7 @@ class ComplexType < Lutaml::Model::Serializable
 
   xml do
     root "GroupOfItems"
+
     map_attribute "tag", to: :tag
     map_content to: :content
     map_element :group, to: :group
@@ -1659,6 +1756,161 @@ end
 ----
 ====
 
+[[import-model-mappings-inside-sequence]]
+==== Using `import_model_mappings` inside a `sequence`
+
+You can use `import_model_mappings` within a `sequence` block to include the element mappings from another model. This is useful for composing complex XML structures from reusable model components.
+
+The element mappings will be imported inside this specific `sequence` block that calls the import method, rest of the mappings like `content`, `attributes`, etc. will be inserted at the class level.
+
+NOTE: `import_model` and `import_model_attributes` are not supported inside a `sequence` block.
+
+[example]
+====
+[source,ruby]
+----
+class Address < Lutaml::Model::Serializable
+  attribute :street, :string
+  attribute :city, :string
+  attribute :zip, :string
+
+  xml do
+    no_root
+
+    map_element :street, to: :street
+    map_element :city, to: :city
+    map_element :zip, to: :zip
+  end
+end
+
+class Person < Lutaml::Model::Serializable
+  attribute :name, :string
+  import_model_attributes Address
+
+  xml do
+    root "Person"
+
+    map_element :name, to: :name
+    sequence do
+      import_model_mappings Address
+    end
+  end
+end
+
+# Example XML output:
+valid_xml = <<~XML
+<Person>
+  <name>John Doe</name>
+  <street>123 Main St</street>
+  <city>Metropolis</city>
+  <zip>12345</zip>
+</Person>
+XML
+invalid_xml = <<~XML
+<Person>
+  <name>John Doe</name>
+  <street>123 Main St</street>
+  <zip>12345</zip>
+</Person>
+XML
+Person.from_xml(valid_xml) # #<Person:0x00000002d56b3988 @city="Metropolis", @name="John Doe", @street="123 Main St", @zip="12345">
+Person.from_xml(invalid_xml) # raises `Element `zip` does not match the expected sequence order element `city` (Lutaml::Model::IncorrectSequenceError)`
+----
+====
+
+[[import-model-attributes-inside-choice]]
+==== Using import_model_attributes inside a choice block
+
+You can use `import_model_attributes` within a `choice` block to allow a model to accept one or more sets of attributes from other models, with flexible cardinality. This is especially useful when you want to allow a user to provide one or more alternative forms of information (e.g., contact methods) in your model.
+
+For example, suppose you want a `Person` model that can have either an `email`, a `phone`, or both as contact information. You can define `ContactEmail` and `ContactPhone` as importable models, and then use `import_model_attributes` for both, inside a `choice` block in the `Person` model.
+
+NOTE: The `import_model_attributes` method is used to import the attributes from the other model into the current model. The imported attributes will be associated to the `choice` block that calls the import method.
+
+[example]
+====
+[source,ruby]
+----
+class ContactEmail < Lutaml::Model::Serializable
+  attribute :email, :string
+
+  xml do
+    no_root
+
+    map_element :email, to: :email
+  end
+end
+
+class ContactPhone < Lutaml::Model::Serializable
+  attribute :phone, :string
+
+  xml do
+    no_root
+
+    map_element :phone, to: :phone
+  end
+end
+
+class Person < Lutaml::Model::Serializable
+  # Allow either or both contact methods, but at least one must be present
+  choice(min: 1, max: 2) do
+    import_model_attributes ContactEmail
+    import_model_attributes ContactPhone
+  end
+
+  xml do
+    root "Person"
+
+    map_element :email, to: :email
+    map_element :phone, to: :phone
+  end
+end
+
+valid_xml = <<~XML
+<Person>
+  <email>john.doe@example.com</email>
+  <phone>1234567890</phone>
+</Person>
+XML
+
+Person.from_xml(valid_xml).validate! # #<Person:0x00000002d0e27fe8 @email="john.doe@example.com", @phone="1234567890">
+
+invalid_xml = <<~XML
+<Person></Person>
+XML
+
+Person.from_xml(invalid_xml).validate! # raises `Lutaml::Model::ValidationError` error
+----
+====
+
+==== Using register functionality
+
+The register functionality is useful when you want to reference or reuse a model by a symbolic name (e.g., across files or in dynamic scenarios), rather than by direct class reference.
+
+.Importing a model using a `Register`
+[example]
+====
+[source,ruby]
+----
+register = Lutaml::Model::Register.new(:importable_model)
+register.register_model(GroupOfItems, id: :group_of_items)
+----
+
+The `id: :group_of_items` assigns a symbolic name to the registered model, which can then be used in `import_model :group_of_items`.
+
+[source,ruby]
+----
+class GroupOfSubItems < Lutaml::Model::Serializable
+  import_model :group_of_items
+end
+----
+====
+
+The `import_model :group_of_items` will behave the same as `import_model GroupOfItems` except the class is resolved from the provided `register`.
+
+NOTE: All the `import_*` methods support the use of `register` functionality.
+
+NOTE: For more details on registers, see <<custom_registers, Custom Registers>>.
 
 [[attribute-value-transform]]
 === Attribute value transform
@@ -1974,156 +2226,1474 @@ For the following XML snippet:
 ----
 ====
 
-== Serialization model mappings
+
+== Collections
 
 === General
 
-Lutaml::Model allows you to translate a data model into serialization models of
-various serialization formats including XML, JSON, YAML, and TOML.
+Collections are used to represent a contained group of multiple instances of models.
 
-Depending on the serialization format, different methods are supported for
-defining serialization and deserialization mappings.
+Typically, a collection represents an "Array" or a "Set" in information modeling
+and programming languages. In LutaML, a collection represents an array of model
+instances.
 
-Serialization model mappings are defined under the `xml`, `json`, `yaml`, and
-`toml` blocks.
+Models in a collection may be:
 
-.Using the `xml`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
-[source,ruby]
-----
-class Example < Lutaml::Model::Serializable
-  xml do
-    # ...
-  end
+* constrained to be of a single kind;
 
-  json do
-    # ...
-  end
+* constrained to be of multiple kinds sharing common characteristics;
 
-  yaml do
-    # ...
-  end
+* unbounded of any kind.
 
-  toml do
-    # ...
-  end
+LutaML Model provides the `Lutaml::Model::Collection` class for defining
+collections of model instances.
 
-  key_value do
-    # ...
-  end
+=== Configuration
+
+==== All formats
+
+The `instances` directive defined at the `Collection` class level is used to
+define the collection attribute and the model type of the collection elements.
+
+Syntax:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, {ModelType}
 end
 ----
 
+Where,
 
-=== XML
-
-==== Setting root element name
+`attribute`:: The name of the attribute that contains the collection.
+`ModelType`:: The model type of the collection elements.
 
-The `root` method sets the root element tag name of the XML document.
 
-If `root` is not given, then the snake-cased class name will be used as the
-root.
+==== Mapping instances: key-value formats only
 
-[example]
-Sets the tag name for `<example>` in XML `<example>...</example>`.
+The `map_instances` directive is only used in the `key_value` block.
 
 Syntax:
 
 [source,ruby]
 ----
-xml do
-  root 'xml_element_name'
-end
-----
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
 
-.Setting the root element name to `example`
-[example]
-====
-[source,ruby]
-----
-class Example < Lutaml::Model::Serializable
-  xml do
-    root 'example'
+  key_value do
+    map_instances to: {attribute}
   end
 end
 ----
 
-[source,ruby]
-----
-> Example.new.to_xml
-> #<example></example>
-----
-====
+Where,
 
+`attribute`:: The name of the attribute that contains model instances.
 
-==== Ommiting root element
+This directive maps individual array elements to the defined `instances`
+attribute. These are the items considered part of the Collection and reflected
+as Enumerable elements.
 
-The root element can be omitted by using the `no_root` method.
 
-When `no_root` is used, only `map_element` can be used because without a root
-element there cannot be attributes.
+==== Mapping instances: XML only
 
-Syntax:
+In the `xml` block, the `map_element`, `map_attribute` directives are used instead.
 
-[source,ruby]
-----
-xml do
-  no_root
-end
-----
+These directives map individual array elements to the defined `instances`
+attribute. These are the items considered part of the Collection and reflected
+as Enumerable elements.
+
+Syntax for an element collection:
 
-[example]
-====
 [source,ruby]
 ----
-class NameAndCode < Lutaml::Model::Serializable
-  attribute :name, :string
-  attribute :code, :string
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
 
   xml do
-    no_root
-    map_element "code", to: :code
-    map_element "name", to: :name
+    map_element "element-name", to: {attribute}
   end
 end
 ----
 
-[source,xml]
-----
-<name>Name</name>
-<code>ID-001</code>
-----
+Where,
+
+`element-name`:: The name of the XML element of each model instance.
+
+
+Syntax for an attribute collection:
 
 [source,ruby]
 ----
-> parsed = NameAndCode.from_xml(xml)
-> # <NameAndCode:0x0000000107a3ca70 @code="ID-001", @name="Name">
-> parsed.to_xml
-> # <code>ID-001</code><name>Name</name>
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
+  xml do
+    map_attribute "attribute-name", to: {attribute}
+  end
+end
 ----
-====
 
+Where,
 
+`attribute-name`:: The name of the XML attribute that contains all model instances.
 
-[[xml-map-all]]
-==== Mapping all XML content
 
-The `map_all` tag in XML mapping captures and maps all content within an XML
-element into a single attribute in the target Ruby object.
+=== Collection types
 
-The use case for `map_all` is to tell Lutaml::Model to not parse the content of
-the XML element at all, and instead handle it as an XML string.
+A LutaML collections is used for a number of scenarios:
 
-NOTE: The corresponding method for key-value formats is at <<key-value-map-all>>.
+* Root collections (for key-value formats)
+* Named collections
+* Keyed collections (for key-value formats)
+* Attribute collections
+* Nested collections
+// * Polymorphic collections
+// * Polymorphic attribute collections
 
-WARNING: Notice that usage of mapping all will lead to incompatibility between
-serialization formats, i.e. the raw string content will not be portable as
-objects are across different formats.
 
-This is useful in the case where the content of an XML element is not to be
-handled by a Lutaml::Model::Serializable object.
+=== Root collections (key-value formats only)
 
-This feature is commonly used with custom methods or a custom model object to
-handle the content.
+==== General
+
+TODO: This case needs to be fixed for JSON.
+
+A root collection is a collection that is not contained within a parent
+collection.
+
+Root collections only apply to key-value serialization formats.
+The XML format does not support root collections.
+
+NOTE: The https://www.w3.org/TR/xml11/[XML standard] mandates the existence
+of a non-repeated "root element" in an XML document. This means that a valid XML
+document must have a root element, and all elements in an XML document must
+exist within the root. This is why an XML document cannot be a "root collection".
+
+NOTE: A root collection cannot be represented using a non-collection model.
+
+Root collections store multiple instances of the same model type at the root
+level. In other words, these are model instances that do not have a defined
+container at the level of the LutaML Model.
+
+There are two kinds of root collections depending on the type of the instance
+value:
+
+"Root value collection":: the value is a "primitive type"
+
+"Root object collection":: the value is a "model instance"
+
+Regardless of the type of root collection, the instance in a collection is
+always a LutaML model instance.
+
+
+==== Root value collections
+
+A root value collection is a collection that directly contains values of a
+primitive type.
+
+.Simple root collection with each instance being a value
+[example]
+====
+[source,yaml]
+----
+---
+- Item One
+- Item Two
+- Item Three
+----
+
+[source,json]
+----
+[
+  "Item One",
+  "Item Two",
+  "Item Three"
+]
+----
+====
+
+
+Syntax:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances :items, ModelType
+end
+
+class ModelType < Lutaml::Model::Serializable
+  attribute :name, :string
+end
+----
+
+.Handling a root collection where each instance is a value
+[example]
+====
+Code:
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  attribute :content, :string
+end
+
+class TitleCollection < Lutaml::Model::Collection
+  instances :titles, Title
+
+  key_value do
+    no_root # default
+    map_instances to: :titles
+  end
+end
+----
+
+Data:
+
+[source,yaml]
+----
+---
+- Title One
+- Title Two
+- Title Three
+----
+
+[source,json]
+----
+[
+  "Title One",
+  "Title Two",
+  "Title Three"
+]
+----
+
+Usage:
+
+[source,ruby]
+----
+titles = TitleCollection.from_yaml(yaml_data)
+titles.count
+# => 3
+titles.first.content
+# => "Title One"
+----
+====
+
+
+==== Root object collections
+
+A root object collection is a collection that directly contains model instances,
+each containing at least one serialized attribute.
+
+.Simple root collection in YAML with each instance being a models with an attribute `name`
+[example]
+====
+[source,yaml]
+----
+---
+- name: Item One
+- name: Item Two
+- name: Item Three
+----
+
+[source,json]
+----
+[
+  {"name": "Item One"},
+  {"name": "Item Two"},
+  {"name": "Item Three"}
+]
+----
+====
+
+
+.Handling a root collection where each instance is defined by a model with attributes
+[example]
+====
+Code:
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  attribute :content, :string
+end
+
+class TitleCollection < Lutaml::Model::Collection
+  instances :titles, Title
+
+  key_value do
+    no_root # default
+    map_instances to: :titles
+  end
+end
+----
+
+Data:
+
+[source,yaml]
+----
+---
+- content: Title One
+- content: Title Two
+- content: Title Three
+----
+
+[source,json]
+----
+[
+  {"content": "Title One"},
+  {"content": "Title Two"},
+  {"content": "Title Three"}
+]
+----
+
+Usage:
+
+[source,ruby]
+----
+titles = TitleCollection.from_yaml(yaml_data)
+titles.count
+# => 3
+titles.first.content
+# => "Title One"
+----
+====
+
+
+=== Named collections
+
+==== General
+
+Named collections are collections wrapped inside a name or a key. The "name" of
+the collection serves as the container root of its contained model instances.
+
+The named collection setup applies to XML and key-value serialization formats.
+
+In a named collection setup, the collection is defined as a
+Lutaml::Model::Collection class, and each instance is defined as a
+Lutaml::Model::Serializable class.
+
+There are two kinds of named collections depending on the type of the instance
+value:
+
+"Named value collection":: the value is a "primitive type"
+
+"Named object collection":: the value is a "model instance"
+
+Regardless of the name of root collection, the instance in a collection is
+always a LutaML model instance.
+
+
+==== Named value collections
+
+A named value collection is a collection that contains values of a
+primitive type.
+
+.Named value collection in XML with models each containing an element with content
+[source,xml]
+----
+<names>
+  <name>Item One</name>
+  <name>Item Two</name>
+  <name>Item Three</name>
+</names>
+----
+
+.Named value collection in YAML with models each containing a value
+[source,yaml]
+----
+---
+names:
+- Item One
+- Item Two
+- Item Three
+----
+
+Syntax:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances :items, ModelType
+
+  xml do
+    root "name-of-xml-container-element"
+  end
+
+  key_value do
+    root "name-of-key-value-container-element"
+  end
+end
+
+class ModelType < Lutaml::Model::Serializable
+  attribute :name, :string
+end
+----
+
+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
+additional attributes and methods.
+
+.Handling a named collection with instance elements directly containing values
+[example]
+====
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  attribute :title, :string
+
+  xml do
+    root "title"
+    map_content to: :title
+  end
+end
+
+class DirectTitleCollection < Lutaml::Model::Collection
+  instances :items, Title
+
+  xml do
+    root "titles"
+    map_element "title", to: :items
+  end
+
+  key_value do
+    map_instances to: :items
+  end
+end
+----
+
+[source,xml]
+----
+<titles>
+  <title>Title One</title>
+  <title>Title Two</title>
+  <title>Title Three</title>
+</titles>
+----
+
+[source,yaml]
+----
+---
+titles:
+- Title One
+- Title Two
+- Title Three
+----
+
+[source,json]
+----
+{
+  "titles": [
+    "Title One",
+    "Title Two",
+    "Title Three"
+  ]
+}
+----
+
+[source,ruby]
+----
+titles = DirectTitleCollection.from_yaml(yaml_data)
+titles.count
+# => 3
+titles.first.title
+# => "Title One"
+titles.last.title
+# => "Title Three"
+----
+====
+
+
+==== Named object collections
+
+A named object collection is a collection that contains model instances,
+each containing at least one serialized attribute.
+
+NOTE: A named object 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 additional attributes and methods.
+
+
+.Named object collection in XML with instances each containing an element with a model attribute
+[source,xml]
+----
+<names>
+  <name><content>Item One</content></name>
+  <name><content>Item Two</content></name>
+  <name><content>Item Three</content></name>
+</names>
+----
+
+.Named object collection in YAML with instances each containing a model attribute
+[source,yaml]
+----
+---
+names:
+- name: Item One
+- name: Item Two
+- name: Item Three
+----
+
+
+.Named object collection with each instance containing at least one model attribute
+[example]
+====
+Data:
+
+[source,xml]
+----
+<titles>
+  <title><content>Title One</content></title>
+  <title><content>Title Two</content></title>
+  <title><content>Title Three</content></title>
+</titles>
+----
+
+[source,yaml]
+----
+---
+titles:
+- title: Title One
+- title: Title Two
+- title: Title Three
+----
+
+[source,json]
+----
+{
+  "titles": [
+    {"title": "Title One"},
+    {"title": "Title Two"},
+    {"title": "Title Three"}
+  ]
+}
+----
+
+Code:
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  attribute :title, :string
+
+  xml do
+    root "title"
+    map_element "content", to: :title
+  end
+
+  key_value do
+    map "title", to: :title
+  end
+end
+
+class TitleCollection < Lutaml::Model::Collection
+  instances :items, Title
+
+  xml do
+    root "titles"
+    map_element 'title', to: :items
+  end
+
+  key_value do
+    root "titles"
+    map_instances to: :items
+  end
+end
+----
+
+Usage:
+
+[source,ruby]
+----
+titles = TitleCollection.from_yaml(yaml_data)
+titles.count
+# => 3
+titles.first.title
+# => "Title One"
+titles.last.title
+# => "Title Three"
+----
+====
+
+
+=== Attribute collection class
+
+A model attribute that is a collection can be contained within a custom
+collection class.
+
+A custom collection class can be defined to provide custom behavior for the
+collection inside a non-collection model, with attributes using
+`collection: true`.
+
+Syntax:
+
+[source,ruby]
+----
+class MyModel < Lutaml::Model::Serializable
+  attribute {model-attribute}, ModelType, collection: MyCollection
+end
+
+class MyCollection < Lutaml::Model::Collection
+  instances {instance-name}, ModelType
+
+  # Custom behavior for the collection
+  def custom_method
+    # Custom logic here
+  end
+end
+----
+
+.Using a custom collection class for custom collection behavior
+[example]
+====
+Data:
+
+[source,xml]
+----
+<titles>
+  <title>Title One</title>
+  <title>Title Two</title>
+  <title>Title Three</title>
+</titles>
+----
+
+[source,yaml]
+----
+titles:
+- title: Title One
+- title: Title Two
+- title: Title Three
+----
+
+
+[source,ruby]
+----
+class StringParts < Lutaml::Model::Collection
+  instances :parts, :string
+
+  def to_s
+    parts.join(' -- ')
+  end
+end
+
+class BibliographicItem < Lutaml::Model::Serializable
+  attribute :title_parts, :string, collection: StringParts
+
+  xml do
+    root "titles"
+    map_element "title", to: :title_parts
+  end
+
+  key_value do
+    root "titles"
+    map_instances to: :title_parts
+  end
+
+  def render_title
+    title_parts.to_s
+  end
+end
+----
+
+[source,ruby]
+----
+> bib_item = BibliographicItem.from_xml(xml_data)
+> bib_item.title_parts
+> # StringParts:0x0000000104ac7240 @parts=["Title One", "Title Two", "Title Three"]
+> bib_item.render_title
+> # "Title One -- Title Two -- Title Three"
+----
+====
+
+
+
+=== Nested collections
+
+TODO: This case needs to be fixed.
+
+Collections can be nested within other models and define their own serialization
+rules.
+
+Nested collections can be defined in the same way as root collections, but
+they are defined within the context of a parent model.
+
+[example]
+====
+Data:
+
+[source,xml]
+----
+<titles>
+  <title-group>
+    <artifact>
+      <content>Title One</content>
+    </artifact>
+    <artifact>
+      <content>Title Two</content>
+    </artifact>
+    <artifact>
+      <content>Title Three</content>
+    </artifact>
+  </title-group>
+</titles>
+----
+
+[source,yaml]
+----
+---
+titles:
+  title-group:
+    - artifact:
+        content: Title One
+    - artifact:
+        content: Title Two
+    - artifact:
+        content: Title Three
+----
+
+[source,ruby]
+----
+class Title < Lutaml::Model::Serializable
+  attribute :content, :string
+end
+
+class TitleCollection < Lutaml::Model::Collection
+  instances :items, Title
+
+  xml do
+    root "title-group"
+    map_element "artifact", to: :items
+  end
+end
+
+class BibItem < Lutaml::Model::Serializable
+  attribute :titles, TitleCollection
+
+  xml do
+    root "bibitem"
+    # This overrides the collection's root "title-group"
+    map_element "titles", to: :titles
+  end
+end
+----
+====
+
+
+=== Keyed collections (key-value serialization formats only)
+
+==== General
+
+In key-value serialization formats, a key can be used to uniquely identify each
+instance. This usage allows for enforcing uniqueness in the collection.
+
+A collection that contains keyed objects as its instances is commonly called a
+"keyed collection". A keyed object in a serialization format is an object
+identified with a unique key.
+
+NOTE: The concept of keyed collections does not typically apply to XML
+collections.
+
+There are two kinds of keyed collections depending on the type of the keyed
+value:
+
+"keyed value collection":: the value is a "primitive type"
+
+"keyed object collection":: the value is a "model instance"
+
+Regardless of the type of keyed collections, the instance in a collection is
+always a LutaML model instance.
+
+
+==== `map_key` method
+
+The `map_key` method specifies that the unique key is to be moved into an
+attribute belonging to the instance model.
+
+Syntax:
+
+[source,ruby]
+----
+key_value do
+  map_key to_instance: {instance-attribute-name}
+end
+----
+
+Where,
+
+`to_instance`:: Refers to the attribute name in the instance that contains the key.
+`{key_attribute}`:: The attribute name in the instance that contains the key.
+
+
+==== `map_value` method
+
+The `map_value` method specifies that the value (the object referenced by the
+unique key) is to be moved into an attribute belonging to the instance model.
+
+Syntax:
+
+[source,ruby]
+----
+key_value do
+  # basic pattern
+  map_value {operation}: [*argument]
+
+  # Mapping the value object to a full instance through `to_instance`
+  map_value to_instance: {instance-attribute-name}
+
+  # Mapping the value object to an attribute as_instance
+  map_value as_attribute: {instance-attribute-name}
+end
+----
+
+==== Keyed value collections
+
+A keyed value collection is a collection where the keyed item in the serialization
+format is a primitive type (e.g. string, integer, etc.).
+
+The instance item inside the collection is a model instance that contains both
+the serialized key and serialized value both as attributes inside the model.
+
+All three `map_key`, `map_value`, and `map_instances` methods need to be used to
+define how instances are mapped in a keyed value collection.
+
+.Creating a keyed value collection
+[example]
+====
+[source,ruby]
+----
+class AuthorAvailability < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :available, :boolean
+end
+
+class AuthorCollection < Lutaml::Model::Collection
+  instances :authors, AuthorAvailability
+
+  key_value do
+    map_key to_instance: :id # This refers to 'authors[].id'
+    map_value as_attribute: :available # This refers to 'authors[].available'
+    map_instances to: :authors
+  end
+end
+----
+
+[source,yaml]
+----
+---
+author_01: true
+author_02: false
+author_03: true
+----
+
+[source,ruby]
+----
+authors = AuthorCollection.from_yaml(yaml_data)
+authors.first.id
+# => "author_01"
+authors.first.available
+# => true
+----
+====
+
+
+==== Keyed object collections
+
+A keyed object collection is a collection where the keyed item in the
+serialization format contains multiple attributes.
+
+The instance item inside the collection is a model instance that contains the
+serialized key as one attribute, and the serialized value attributes are all
+attributes inside the model.
+
+Both the `map_key` and `map_instances` are used to define how instances are
+mapped in a keyed object collection.
+
+.Creating a keyed object collection
+[example]
+====
+[source,ruby]
+----
+class Author < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :name, :string
+end
+
+class AuthorCollection < Lutaml::Model::Collection
+  instances :authors, Author
+
+  key_value do
+    map_key to_instance: :id # This refers to 'authors[].id'
+    map_instances to: :authors
+  end
+end
+----
+
+[source,yaml]
+----
+---
+author_01:
+  name: Author One
+author_02:
+  name: Author Two
+author_03:
+  name: Author Three
+----
+
+[source,ruby]
+----
+authors = AuthorCollection.from_yaml(yaml_data)
+authors.first.id
+# => "author_01"
+authors.first.name
+# => "Author One"
+----
+====
+
+
+==== Nested keyed object collection
+
+A nested keyed object collection is a keyed collection that contain other keyed
+collections. This case is simply a more complex arrangement of the principles
+applied to keyed object collections.
+
+This pattern can extend to multiple levels of nesting, where each level contains
+a keyed object collection that can have its own key and value mappings.
+
+Depends on whether a custom collection class is needed, the following
+mechanisms are available:
+
+* When using a Lutaml::Model::Serializable class for a keyed collection,
+use the `child_mappings` option to map attributes.
+
+* When using a Lutaml::Model::Collection class for a keyed collection,
+there are two options:
+
+* use the `map_key`, `map_value`, and `map_instances` methods to map attributes;
+or
+
+* use the `root_mappings` option to map attributes.
+
+
+.Nested 2-layer keyed object collection
+[example]
+====
+This example provides a two-layer nested structure where:
+
+* The first layer keys pieces by type (`bowls`, `vases`).
+* The second layer keys glazes by finish name within each piece type.
+* Each glaze finish contains detailed attributes like temperature.
+
+[source,ruby]
+----
+# Third layer represents glaze finishes.
+class GlazeFinish < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :temperature, :integer
+
+  key_value do
+    map "name", to: :name
+    map "temperature", to: :temperature
+  end
+end
+
+# Second layer represents ceramic pieces each with multiple finishes.
+class CeramicPiece < Lutaml::Model::Serializable
+  attribute :piece_type, :string
+  attribute :glazes, GlazeFinish, collection: true
+
+  key_value do
+    map "piece_type", to: :piece_type
+    map "glazes", to: :glazes, child_mappings: {
+      name: :key,
+      temperature: :temperature
+    }
+  end
+end
+
+# Uppermost layer represents the collection of ceramic pieces.
+class StudioInventory < Lutaml::Model::Collection
+  instances :pieces, CeramicPiece
+
+  key_value do
+    map to: :pieces, root_mappings: {
+      piece_type: :key,
+      glazes: :value,
+    }
+  end
+end
+----
+
+[source,yaml]
+----
+---
+bowls:
+  matte_finish:
+    name: Earth Matte
+    temperature: 1240
+  glossy_finish:
+    name: Ocean Blue
+    temperature: 1260
+  crackle_finish:
+    name: Antique Crackle
+    temperature: 1220
+vases:
+  metallic_finish:
+    name: Bronze Metallic
+    temperature: 1280
+  crystalline_finish:
+    name: Ice Crystal
+    temperature: 1300
+----
+
+[source,ruby]
+----
+inventory = StudioInventory.from_yaml(yaml_data)
+
+# Access nested data through the hierarchy
+puts inventory.pieces.bowls.matte_finish.name
+# => "Earth Matte"
+
+puts inventory.pieces.bowls.matte_finish.temperature
+# => 1240
+
+# Iterate through all pieces and their glazes
+inventory.pieces.each do |piece_type, piece|
+  puts "#{piece_type.capitalize}:"
+  piece.glazes.each do |glaze_name, glaze|
+    puts "  #{glaze_name}: #{glaze.name} (#{glaze.temperature}°C)"
+  end
+end
+----
+====
+
+
+
+
+=== Behavior
+
+==== Enumerable interface
+
+Collections implement the Ruby `Enumerable` interface, providing standard
+collection operations.
+
+Collections allow the following sample `Enumerable` methods:
+
+* `each` - Iterate over collection items
+* `map` - Transform collection items
+* `select` - Filter collection items
+* `find` - Find items matching criteria
+* `reduce` - Aggregate collection items
+
+.Usage of the collection Enumerable interface
+[example]
+====
+[source,ruby]
+----
+# Filter items
+filtered = collection.filter { |item| item.id == "1" }
+
+# Reject items
+rejected = collection.reject { |item| item.id == "1" }
+
+# Select items
+selected = collection.select { |item| item.id == "1" }
+
+# Map items
+mapped = collection.map { |item| item.name }
+
+# Count items
+count = collection.count
+----
+====
+
+
+// ==== Collection validation
+
+// Collections can define validation rules for their elements.
+
+// [example]
+// ====
+// [source,ruby]
+// ----
+// class PublicationCollection < Lutaml::Model::Collection
+//   instances(:publications, Publication) do
+//     validates :year, numericality: { greater_than: 1900 }
+
+//     validate :must_have_author
+
+//     def must_have_author(publications)
+//       publications.each do |publication|
+//         next unless publication.author.nil?
+//         errors.add(:author, "`#{publication.title}` must have an author")
+//       end
+//     end
+//   end
+// end
+// ----
+// ====
+
+==== Initialization
+
+Collections can be initialized with an array of items or through individual item
+addition.
+
+[example]
+====
+[source,ruby]
+----
+# Empty collection
+collection = ItemCollection.new
+
+# From an array of items
+collection = ItemCollection.new([item1, item2, item3])
+
+# From an array of hashes
+collection = ItemCollection.new([
+  { id: "1", name: "Item 1" },
+  { id: "2", name: "Item 2" }
+])
+
+# Adding items later
+collection << Item.new(id: "3", name: "Item 3")
+----
+====
+
+==== Ordering
+
+TODO: This case needs to be fixed.
+
+Collections that maintain a specific ordering of elements.
+
+Syntax:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances {instances-name}, ModelType
+  ordered by: {attribute-of-instance}, order: {:asc | :desc}
+end
+----
+
+Where,
+
+`{instances-name}`:: name of the instances accessor within the collection
+`ModelType`:: The model type of the collection elements.
+
+`{attribute-of-instance-or-proc}`:: How model instances are to be ordered by. Values supported are:
+`{attribute-of-instance}`::: Attribute name of an instance to be ordered by.
+`{proc}`::: Proc that returns a value to order by (same as `sort_by`), given the instance as input.
+
+`order`::: Order direction of the value:
+`:asc`:::: Ascending order (default).
+`:desc`:::: Descending order.
+
+.Ordered collection applied to a root collection
+[example]
+====
+Data:
+
+[source,xml]
+----
+<items>
+  <item id="3" name="Item Three"/>
+  <item id="1" name="Item One"/>
+  <item id="2" name="Item Two"/>
+</items>
+----
+
+[source,yaml]
+----
+---
+- id: 3
+  name: Item Three
+- id: 1
+  name: Item One
+- id: 2
+  name: Item Two
+----
+
+[source,ruby]
+----
+class Item < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :name, :string
+
+  xml do
+    map_attribute "id", to: :id
+    map_attribute "name", to: :name
+  end
+end
+
+class OrderedItemCollection < Lutaml::Model::Collection
+  instances :items, Item
+  ordered by: :id, order: :desc
+
+  xml do
+    root "items"
+    map_element "item", to: :items
+  end
+
+  key_value do
+    no_root
+    map_instances to: :items
+  end
+end
+----
+
+[source,ruby]
+----
+> collection = OrderedItemCollection.from_xml(xml_data)
+> collection.map(&:id)
+> # ["3", "2", "1"]
+
+> collection = OrderedItemCollection.from_yaml(yaml_data)
+> collection.map(&:id)
+> # ["3", "2", "1"]
+----
+====
+
+
+
+// ==== Polymorphic collections
+
+// Collections can contain instances of different model classes that share a common
+// base class.
+
+// The polymorphic options for attributes are also applied here.
+
+// [example]
+// ====
+// [source,ruby]
+// ----
+// class PolymorphicItemCollection < Lutaml::Model::Collection
+//   instances :items, Item, polymorphic: true
+
+//   xml do
+//     root "items"
+//     map_element "item", to: :items
+//   end
+
+//   key_value do
+//     root "items"
+//     map_instances to: :items
+//   end
+// end
+// ----
+// ====
+
+
+== Serialization model mappings
+
+=== General
+
+Lutaml::Model allows you to translate a data model into serialization models of
+various serialization formats.
+
+Depending on the serialization format, different methods are supported for
+defining serialization and deserialization mappings.
+
+A serialization model mapping is defined using a format-specific DSL block
+in this syntax:
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  {format-short-name} do <1>
+    # ...
+  end
+end
+----
+<1> `{format-short-name}` is the serialization format short name.
+
+There are two kinds of serialization models:
+
+* Represents a singular model (maps to a Lutaml::Model::Serializable)
+* Represents a group/collection of models (maps to Lutaml::Model::Collection)
+
+A collection contains instances of singular models, and therefore is always
+inextricably linked to an underlying serialization format for singular models.
+For instance, JSONL represents a collection (itself being invalid JSON) that
+uses JSON for singular models.
+
+The supported serialization formats and their short names are defined as follows:
+
+Model serialization formats::
+
+`xml`::: XML
+`hsh`::: Hash
++
+NOTE: Yes a 3-letter abbreviation for Hash!
+
+`json`::: JSON
+`yaml`::: YAML
+`toml`::: TOML
+`key_value`::: Key-value format, a shorthand for all key-value formats (including
+JSON, YAML and TOML).
+
+Collection serialization formats::
+
+`jsonl`::: JSONL (JSON Lines)
+`yamls`::: YAML Stream (multi-document format)
+
+
+.Using the `xml`, `hsh`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
+[example]
+====
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  xml do
+    # ...
+  end
+
+  hsh do
+    # ...
+  end
+
+  json do
+    # ...
+  end
+
+  yaml do
+    # ...
+  end
+
+  toml do
+    # ...
+  end
+
+  key_value do
+    # ...
+  end
+end
+----
+====
+
+.Using the `jsonl` block to define serialization mappings to a collection
+[example]
+====
+[source,ruby]
+----
+class Example < Lutaml::Model::Collection
+  jsonl do
+    # ...
+  end
+end
+----
+====
+
+
+=== XML
+
+==== Setting root element name
+
+The `root` method sets the root element tag name of the XML document.
+
+If `root` is not given, then the snake-cased class name will be used as the
+root.
+
+[example]
+Sets the tag name for `<example>` in XML `<example>...</example>`.
+
+Syntax:
+
+[source,ruby]
+----
+xml do
+  root 'xml_element_name'
+end
+----
+
+.Setting the root element name to `example`
+[example]
+====
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  xml do
+    root 'example'
+  end
+end
+----
+
+[source,ruby]
+----
+> Example.new.to_xml
+> #<example></example>
+----
+====
+
+
+==== Ommiting root element
+
+The root element can be omitted by using the `no_root` method.
+
+When `no_root` is used, only `map_element` can be used because without a root
+element there cannot be attributes.
+
+Syntax:
+
+[source,ruby]
+----
+xml do
+  no_root
+end
+----
+
+[example]
+====
+[source,ruby]
+----
+class NameAndCode < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :code, :string
+
+  xml do
+    no_root
+    map_element "code", to: :code
+    map_element "name", to: :name
+  end
+end
+----
+
+[source,xml]
+----
+<name>Name</name>
+<code>ID-001</code>
+----
+
+[source,ruby]
+----
+> parsed = NameAndCode.from_xml(xml)
+> # <NameAndCode:0x0000000107a3ca70 @code="ID-001", @name="Name">
+> parsed.to_xml
+> # <code>ID-001</code><name>Name</name>
+----
+====
+
+
+
+[[xml-map-all]]
+==== Mapping all XML content
+
+The `map_all` tag in XML mapping captures and maps all content within an XML
+element into a single attribute in the target Ruby object.
+
+The use case for `map_all` is to tell Lutaml::Model to not parse the content of
+the XML element at all, and instead handle it as an XML string.
+
+NOTE: The corresponding method for key-value formats is at <<key-value-map-all>>.
+
+WARNING: Notice that usage of mapping all will lead to incompatibility between
+serialization formats, i.e. the raw string content will not be portable as
+objects are across different formats.
+
+This is useful in the case where the content of an XML element is not to be
+handled by a Lutaml::Model::Serializable object.
+
+This feature is commonly used with custom methods or a custom model object to
+handle the content.
 
 This includes:
 
@@ -2983,6 +4553,7 @@ HERE
 ----
 ====
 
+NOTE: For importing model mappings inside a `sequence` block, refer to <<import-model-mappings-inside-sequence, Importing model mappings inside a `sequence`>>.
 
 [[xml-schema-location]]
 ==== Automatic support of `xsi:schemaLocation`
@@ -3448,11 +5019,20 @@ This XML snippet is in UTF-8.
 
 ==== General
 
-Key-value data models like JSON, YAML, and TOML all share a similar structure
-where data is stored as key-value pairs.
+Key-value data models share a similar structure where data is stored as
+key-value pairs.
 
 `Lutaml::Model` works with these formats in a similar way.
 
+Key-value data models supported are identified by their short name:
+
+`hsh`:: Hash (Ruby `Hash` class)
+`json`:: JSON
+`yaml`:: YAML
+`toml`:: TOML
+`key_value`:: A way to configure key-value mappings for all supported key-value data models.
+
+
 ==== Mapping
 
 The `map` method is used to define key-value mappings.
@@ -3461,16 +5041,40 @@ Syntax:
 
 [source,ruby]
 ----
-json | yaml | toml | key_value do
+{key_value_type_short} do <1>
   map 'key_value_model_attribute_name', to: :name_of_attribute
 end
 ----
+<1> `key_value_type_short` is the key-value data model's short name.
+
+.Creating a key-value data model mapping for only the JSON format
+[example]
+====
+[source,ruby]
+----
+json do
+  map :color, to: :color
+  map :desc, to: :description
+end
+----
+====
 
+.Creating a key-value data model mapping for all key-value formats
+[example]
+====
+[source,ruby]
+----
+key_value do
+  map :color, to: :color
+  map :desc, to: :description
+end
+----
+====
 
 ==== Unified mapping
 
 The `key_value` method is a streamlined way to map all attributes for
-serialization into key-value formats including JSON, YAML, and TOML.
+serialization into key-value formats including Hash, JSON, YAML, and TOML.
 
 If there is no definite differentiation between the key value formats, the
 `key_value` method simplifies defining mappings and improves code readability.
@@ -3489,19 +5093,11 @@ class CeramicModel < Lutaml::Model::Serializable
   attribute :glaze, :string
   attribute :description, :string
 
-  key_value do
-    map :color, to: color
+  key_value do # or any other key-value data model
+    map :color, to: :color
     map :glz, to: :glaze
     map :desc, to: :description
   end
-
-  # Equivalent to the JSON, YAML, and TOML mappings.
-  #
-  # json and yaml and toml do
-  #   map :id, to: color
-  #   map :name, to: :full_name
-  #   map :status, to: :current_status
-  # end
 end
 ----
 
@@ -3532,12 +5128,7 @@ desc: A ceramic with a navy blue color and clear glaze.
 
 ==== Specific format mappings
 
-Specific key value formats can be mapping independently of other formats, including:
-
-* `json` for the JSON format
-* `yaml` for the YAML format
-* `toml` for the TOML format
-
+Specific key value formats can be mapping independently of other formats.
 
 .Using the `map` method to define key-value mappings per format
 [example]
@@ -3548,6 +5139,11 @@ class Example < Lutaml::Model::Serializable
   attribute :name, :string
   attribute :value, :integer
 
+  hsh do
+    map 'name', to: :name
+    map 'value', to: :value
+  end
+
   json do
     map 'name', to: :name
     map 'value', to: :value
@@ -3610,7 +5206,7 @@ Syntax:
 
 [source,ruby]
 ----
-json | yaml | toml | key_value do
+hsh | json | yaml | toml | key_value do
   map_all to: :name_of_attribute
 end
 ----
@@ -3623,6 +5219,10 @@ end
 class Document < Lutaml::Model::Serializable
   attribute :content, :string
 
+  hsh do
+    map_all to: :content
+  end
+
   json do
     map_all to: :content
   end
@@ -3796,7 +5396,7 @@ Syntax:
 class SomeKeyedCollection < Lutaml::Model::Serializable
   attribute :name_of_attribute, AttributeValueType, collection: true
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map to: :name_of_attribute, <1>
       root_mappings: { <2>
         # `:key` is a reserved keyword
@@ -3870,7 +5470,7 @@ Syntax:
 class SomeKeyedCollection < Lutaml::Model::Serializable
   attribute :name_of_attribute, AttributeValueType, collection: true
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map to: :name_of_attribute,
       root_mappings: {
         value_type_attribute_name_for_key: :key, <1>
@@ -4008,7 +5608,7 @@ Syntax:
 class SomeKeyedCollection < Lutaml::Model::Serializable
   attribute :name_of_attribute, AttributeValueType, collection: true
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map to: :name_of_attribute,
       root_mappings: {
         value_type_attribute_name_for_key: :key, <1>
@@ -4214,7 +5814,7 @@ Syntax:
 class SomeKeyedCollection < Lutaml::Model::Serializable
   attribute :name_of_attribute, AttributeValueType, collection: true
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map to: :name_of_attribute,
       root_mappings: {
         value_type_attribute_name_for_key: :key, <1>
@@ -4378,7 +5978,7 @@ end
 NOTE: This feature is for key-value data model serialization only.
 
 The `child_mappings` option is used to extract results from a key-value
-serialization data model (JSON, YAML, TOML) into a `Lutaml::Model::Serializable`
+serialization data model (Hash, JSON, YAML, TOML) into a `Lutaml::Model::Serializable`
 object (collection or not).
 
 The values are extracted from the key-value data model using the list of keys
@@ -4391,7 +5991,7 @@ Syntax:
 class SomeObject < Lutaml::Model::Serializable
   attribute :name_of_attribute, AttributeValueType, collection: true
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map 'key_value_model_attribute_name', to: :name_of_attribute,
       child_mappings: {
         value_type_attribute_name_1: <1>
@@ -4556,12 +6156,353 @@ The output becomes:
 > #{"schemas"=>{"foo"=>{"path"=>{"link"=>"link one", "name"=>"one"}}, {"bar"=>{"path"=>{"link"=>"link two", "name"=>"two"}}}}}
 ----
 
-In this example:
+In this example:
+
+* The `key` of each schema (`foo` and `bar`) is mapped to the `id` attribute.
+
+* The nested `path.link` and `path.name` keys are mapped to the `link` and
+`name` attributes, respectively.
+====
+
+=== Collection data models
+
+==== General
+
+Collection data models represent a group of models, mapping to an instance of
+Lutaml::Model::Collection.
+
+Collection data models supported are identified by their short name:
+
+`jsonl`:: JSONL (JSON Lines)
+`yamls`:: YAML Stream (multi-document format)
+
+
+==== Mapping
+
+As with collections in general, the `map` method is used to define collection
+mappings.
+
+Syntax:
+
+[source,ruby]
+----
+class MySerializedCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
+
+  {collection_type_short} do
+    map_instances to: {attribute}
+  end
+end
+----
+
+Where,
+
+`{collection_type_short}`:: The short name of the collection type (e.g. `jsonl`, `yamls`).
+
+`{attribute}`:: The name of the attribute in the collection that will hold the
+collection data.
+
+`ModelType`:: The type of the model that will be used in the collection.
+
+A singular model may also utilize collection data models in the following manner.
+
+Syntax:
+
+[source,ruby]
+----
+class MySerializedCollection < Lutaml::Model::Serializeable
+  attribute {attribute}, ModelType, collection: true
+
+  {collection_type_short} do
+    # Notice that there is no key_name i.e map <key_name>, to: <attribute_name>,
+    # This is because in a collection there are no keys. Each object needs to be
+    # mapped to the attribute.
+    map to: {attribute}
+  end
+end
+----
+
+Where,
+
+`{collection_type_short}`:: The short name of the collection type (e.g. `jsonl`, `yamls`).
+
+`{attribute}`:: The name of the attribute in the collection that will hold the
+collection data.
+
+`ModelType`:: The type of the model that will be used in the collection.
+
+
+==== JSONL
+
+JSONL (short for JSON Lines) is a serialization format where each line
+represents a valid JSON object. The format is meant to be efficient for large
+datasets such as for streaming or batch processing.
+
+It represents a collection of JSON objects encoded one object per line.
+
+NOTE: The contents of JSONL itself is not valid JSON, but each line is a valid
+JSON.
+
+Since JSONL contains JSON elements, the model specified with `instances` or
+`attribute` must support JSON.
+
+Every line in a JSONL file is also a valid JSON object. If JSONL-specific
+mappings (through `jsonl`) are not defined in the model, the existing `json`
+mappings are used instead as a fallback for serialization and deserialization.
+
+
+.Parsing a JSONL collection using a collection
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+end
+
+class Directory < Lutaml::Model::Collection
+  instances :persons, Person
+
+  jsonl do
+    map_instances to: :persons
+  end
+end
+
+jsonl = <<~JSONL
+  {"name":"John","age":30,"id":"abc-123"}
+  {"name":"Jane","age":25,"id":"def-456"}
+JSONL
+
+jsonl = Directory.from_jsonl(jsonl)
+
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane", @age=25, @id="def-456">
+#     ]>
+----
+====
+
+.Parsing a JSONL collection using a singlular model
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+end
+
+class Directory < Lutaml::Model::Serializeable
+  attribute :persons, Person, collection: true
+
+  jsonl do
+    map_instances to: :persons
+  end
+end
+
+jsonl = <<~JSONL
+  {"name":"John","age":30,"id":"abc-123"}
+  {"name":"Jane","age":25,"id":"def-456"}
+JSONL
+
+jsonl = Directory.from_jsonl(jsonl)
+
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane", @age=25, @id="def-456">
+#     ]>
+----
+====
+
+.Parsing a JSONL collection relying on JSON mappings on instance model
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+
+  json do
+    map "full_name", to: :name
+    map "age", to: :age
+    map "id", to: :id
+  end
+end
+
+class Directory < Lutaml::Model::Collection
+  instances :persons, Person
+
+  jsonl do
+    map_instances to: :persons
+  end
+end
+
+jsonl = <<~JSONL
+  {"full_name":"John Doe","age":30,"id":"abc-123"}
+  {"full_name":"Jane Smith","age":25,"id":"def-456"}
+JSONL
+
+jsonl = Directory.from_jsonl(jsonl)
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John Doe", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane Smith", @age=25, @id="def-456">
+#     ]>
+----
+====
+
+
+==== YAML Stream
+
+YAML Stream (short for YAML multi-document format) is a serialization format
+where each document is separated by a document separator (`---`). The format is
+meant to be efficient for large datasets such as for streaming or batch
+processing.
+
+It represents a collection of YAML documents encoded one document per stream.
+
+NOTE: The contents of YAML Stream is valid YAML, where each document is a valid
+YAML document separated by document separators.
+
+Since YAML Stream contains YAML elements, the model specified with `instances`
+or `attribute` must support YAML.
+
+Every document in a YAML Stream file is also a valid YAML document. If YAML
+Stream-specific mappings (through `yamls`) are not defined in the model, the
+existing `yaml` mappings are used instead as a fallback for serialization and
+deserialization.
+
+
+.Parsing a YAML Stream collection using a collection
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+end
+
+class Directory < Lutaml::Model::Collection
+  instances :persons, Person
+
+  yamls do
+    map_instances to: :persons
+  end
+end
+
+yamls = <<~YAMLS
+  ---
+  name: John
+  age: 30
+  id: abc-123
+  ---
+  name: Jane
+  age: 25
+  id: def-456
+YAMLS
+
+yamls = Directory.from_yamls(yamls)
+
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane", @age=25, @id="def-456">
+#     ]>
+----
+====
+
+.Parsing a YAML Stream collection using a singlular model
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+end
+
+class Directory < Lutaml::Model::Serializeable
+  attribute :persons, Person, collection: true
+
+  yamls do
+    map_instances to: :persons
+  end
+end
+
+yamls = <<~YAMLS
+  ---
+  name: John
+  age: 30
+  id: abc-123
+  ---
+  name: Jane
+  age: 25
+  id: def-456
+YAMLS
+
+yamls = Directory.from_yamls(yamls)
+
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane", @age=25, @id="def-456">
+#     ]>
+----
+====
+
+.Parsing a YAML Stream collection relying on YAML mappings on instance model
+[example]
+====
+[source,ruby]
+----
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+
+  yaml do
+    map "full_name", to: :name
+    map "age", to: :age
+    map "id", to: :id
+  end
+end
 
-* The `key` of each schema (`foo` and `bar`) is mapped to the `id` attribute.
+class Directory < Lutaml::Model::Collection
+  instances :persons, Person
 
-* The nested `path.link` and `path.name` keys are mapped to the `link` and
-`name` attributes, respectively.
+  yamls do
+    map_instances to: :persons
+  end
+end
+
+yamls = <<~YAMLS
+  ---
+  full_name: John Doe
+  age: 30
+  id: abc-123
+  ---
+  full_name: Jane Smith
+  age: 25
+  id: def-456
+YAMLS
+
+yamls = Directory.from_yamls(yamls)
+# => <Directory:0x00007fae4b0c9b10
+#      @persons=[
+#      <Person:0x00007fae4b0c9970 @name="John Doe", @age=30, @id="abc-123">,
+#      <Person:0x00007fae4b0c9838 @name="Jane Smith", @age=25, @id="def-456">
+#     ]>
+----
 ====
 
 === Format-independent mechanisms
@@ -4639,7 +6580,7 @@ being retrieved from the model.
 Attribute-level `import`:: The transformation `Proc` for the value when it is
 being assigned to the model.
 
-`{key_value_formats}`:: The serialization format (e.g. `json`, `yaml`, `toml`,
+`{key_value_formats}`:: The serialization format (e.g. `hsh`, `json`, `yaml`, `toml`,
 `key_value`) for which the mapping is defined.
 
 Mapping-level `transform`:: The option to define a transformation for the
@@ -4738,18 +6679,18 @@ format-specific custom methods.
 ╔════════════════════════════╗       ╔════════════════════════════╗
 ║ Serialization Format Value ║       ║ Serialization Format Value ║
 ╚════════════════════════════╝       ╚════════════════════════════╝
-              |                                    |
-              ▼                                    ▼
+              |                                    ▲
+              ▼                                    |
 ╔════════════════════════════╗       ╔════════════════════════════╗
 ║      Mapping Transform     ║       ║      Mapping Transform     ║
 ╚════════════════════════════╝       ╚════════════════════════════╝
-              |                                    |
-              ▼                                    ▼
+              |                                    ▲
+              ▼                                    |
 ╔════════════════════════════╗       ╔════════════════════════════╗
 ║     Attribute Transform    ║       ║     Attribute Transform    ║
 ╚════════════════════════════╝       ╚════════════════════════════╝
-              |                                    |
-              ▼                                    ▼
+              |                                    ▲
+              ▼                                    |
 ╔════════════════════════════╗       ╔════════════════════════════╗
 ║    Model Attribute Value   ║       ║    Model Attribute Value   ║
 ╚════════════════════════════╝       ╚════════════════════════════╝
@@ -4994,7 +6935,7 @@ xml do
   map_attribute 'name_of_attribute', to: :name_of_attribute, render_default: true
 end
 
-json | yaml | toml | key_value do
+hsh | json | yaml | toml | key_value do
   map 'name_of_attribute', to: :name_of_attribute, render_default: true
 end
 ----
@@ -5071,7 +7012,7 @@ Syntax:
 
 [source,ruby]
 ----
-json | yaml | toml | key_value do
+hsh | json | yaml | toml | key_value do
   map ["name1", "name2"], to: :attribute_name
 end
 
@@ -5185,7 +7126,7 @@ Syntax:
 
 [source,ruby]
 ----
-xml | json | yaml | toml do
+xml | hsh | json | yaml | toml do
   map 'key_value_model_attribute_name', to: :name_of_attribute, delegate: :model_to_delegate_to
 end
 ----
@@ -5466,7 +7407,7 @@ NOTE: For `NokogiriAdapter`, we can also call `to_xml` on `value.node.adapter_no
 .Key-value data model serialization with custom methods
 [source,ruby]
 ----
-json | yaml | toml do
+hsh | json | yaml | toml do
   map 'attribute_name', to: :name_of_attribute, with: {
     to: :method_name_to_serialize,
     from: :method_name_to_deserialize
@@ -5533,12 +7474,122 @@ the undefined value:: the value is not defined
 There are also different ways to represent these missing values
 when the attribute accepts a single value or a collection of values.
 
+.Support of missing value types in different technologies
+|===
+| Technology | Missing value type | Realized as
+
+.3+| Lutaml::Model
+| empty value | Ruby empty string (`""`)
+| non-existent value | Ruby `NilClass` (`nil`)
+| undefined value | `class Uninitialized`
+
+.3+| XML element
+| empty value | XML blank element: `<status></status>` or `<status/>`
+| non-existent value | XML blank element with attribute `xsi:nil`: `<status xsi:nil="true"/>`
+| undefined value | the XML element is omitted
+
+.3+| XML attribute
+| empty value | XML blank attribute: `status=""`
+| non-existent value | the XML attribute is omitted
+| undefined value | the XML attribute is omitted
+
+.3+| JSON
+| empty value | JSON empty string (`""`)
+| non-existent value | JSON `null` value
+| undefined value | the JSON key is omitted
+
+.3+| TOML
+| empty value | TOML empty string
+| non-existent value | the TOML key is omitted since TOML does not support the concept of null.
+| undefined value | the TOML key is omitted
+
+|===
+
+NOTE: The `Uninitialized` class is a special Lutaml::Model construct, it is not
+supported by normal Ruby objects.
+
+The challenge for the developer is how to represent fully compatible semantics
+using interoperable data models across different technologies.
+
+Lutaml::Model provides you with several mechanisms to retain the missing values
+semantics. An example mapping is shown in the following diagram.
+
+.Mapping of missing value types between Lutaml::Model and YAML
+[source]
+----
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  ╔════════════════════════╗                    ╔════════════════════════╗   │
+│  ║  Lutaml::Model Values  ║                    ║      YAML Values       ║   │
+│  ╠════════════════════════╣                    ╠════════════════════════╣   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "empty"               ║◀──────────────────▶║  "empty"               ║   │
+│  ║  (empty string, [])    ║      to empty      ║  (empty string, [])    ║   │
+│  ║                        ║                    ║                        ║   │
+│  ╟────────────────────────╢                    ╟────────────────────────╢   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "non-existent"        ║◀──────────────────▶║  "non-existent"        ║   │
+│  ║  (nil)                 ║  to non-existent   ║  (null)                ║   │
+│  ║                        ║                    ║                        ║   │
+│  ╟────────────────────────╢                    ╟────────────────────────╢   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "undefined"           ║◀──────────────────▶║  "undefined"           ║   │
+│  ║  (uninitialized)       ║   to undefined     ║  (key omitted)         ║   │
+│  ║                        ║                    ║                        ║   │
+│  ╚════════════════════════╝                    ╚════════════════════════╝   │
+└─────────────────────────────────────────────────────────────────────────────┘
+----
+
+In the case where the interoperating technologies do not support the full spectrum
+of missing value types, it is necessary for the developer to understand any
+such behavior and relevant handling.
+
+.Mapping of missing value types between Lutaml::Model and TOML
+[source]
+----
+┌─────────────────────────────────────────────────────────────────────────────┐
+│  ╔════════════════════════╗                    ╔════════════════════════╗   │
+│  ║  Lutaml::Model Values  ║                    ║      TOML Values       ║   │
+│  ╠════════════════════════╣                    ╠════════════════════════╣   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "empty"               ║◀──────────────────▶║  "empty"               ║   │
+│  ║  (empty string, [])    ║      to empty      ║  (empty string, [])    ║   │
+│  ║                        ║                    ║                        ║   │
+│  ╟────────────────────────╢                    ╟────────────────────────╢   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "non-existent"        ║◀──────────────────▶║                        ║   │
+│  ║  (nil)                 ║   to undefined     ║  "undefined"           ║   │
+│  ║                        ║                    ║  (key omitted)         ║   │
+│  ╟────────────────────────╢                    ║                        ║   │
+│  ║                        ║      mapping       ║                        ║   │
+│  ║  "undefined"           ║─────(one-way)─────▶║     TOML does not      ║   │
+│  ║  (uninitialized)       ║   to undefined     ║     support NULL       ║   │
+│  ║                        ║                    ║                        ║   │
+│  ╚════════════════════════╝                    ╚════════════════════════╝   │
+└─────────────────────────────────────────────────────────────────────────────┘
+----
+
+There are the following additional challenges that a developer must take into account of:
+
+* Single attribute value vs collection attribute value. Different technologies
+treat single/collection values differently.
+
+* External schemas and systems that interoperate with serializations from
+Lutaml::Model. Many schemas and systems adopt "different" conventions for
+representing missing value semantics (sometimes very awkward ones).
+
+The solution for the first challenge is to understand the behavior of the
+different technologies used. The default mappings are described in <<value_representation_in_lutaml-model>>
+and <<value_representation_in_serialization_formats>>.
+
+
+[[value_representation_in_lutaml-model]]
 ==== Value representation in Lutaml::Model
 
 The following table summarizes the behavior of the Lutaml::Model
 in regards of the "missing values" family.
 
-[cols="1,1,1,1", options="header"]
+.Handling of missing value types in Lutaml::Model data types
+[cols="1,1,2,2"]
 |===
 | LutaML value type | Cardinality (1 or n) | Missing value type | Ruby value
 
@@ -5556,55 +7607,49 @@ in regards of the "missing values" family.
 
 .3+| `:integer`
 .3+| single
-| empty value | `0` (Integer)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:float`
 .3+| single
-| empty value | `0.0` (Float)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:boolean`
 .3+| single
-| empty value | `false` (FalseClass)
-| non-existent value | `nil` (NilClass)
-| undefined value | No assigned value
-
-.3+| `:date`
-.3+| single
-| empty value | `Date.new(0)` (Date)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:date`
 .3+| single
-| empty value | `Date.new(0)` (Date)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:time_without_date`
 .3+| single
-| empty value | `Time.new(0)` (Time)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:date_time`
 .3+| single
-| empty value | `Time.new(0)` (Time)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:time`
 .3+| single
-| empty value | `Time.new(0)` (Time)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:decimal`
 .3+| single
-| empty value | `BigDecimal.new(0)` (BigDecimal)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
@@ -5617,6 +7662,7 @@ in regards of the "missing values" family.
 |===
 
 
+[[value_representation_in_serialization_formats]]
 ==== Value representation in serialization formats
 
 Every serialization format uses a different information model to represent
@@ -5674,6 +7720,8 @@ while others only support a subset of them.
 
 ==== Missing value mapping
 
+===== General
+
 Lutaml::Model provides a comprehensive way to handle the missing values family
 across different serialization formats.
 
@@ -5689,7 +7737,8 @@ A hash of key-value pairs that determines the mapping of a missing value at the
 The key is the missing value type in the serialization format, and the value is
 the missing value type in the LutaML Model.
 +
-NOTE: In other words, used when converting the serialized format into a Ruby object.
+NOTE: In other words, used when converting the serialized format into a
+Lutaml::Model Ruby object.
 
 `to` pairs::
 A hash of key-value pairs that determines the mapping of a LutaML Model ("to") missing
@@ -5697,7 +7746,8 @@ to a missing value choice at the serialization format where this mapping applies
 The key is the missing value type in the LutaML Model, and the value is the
 missing value type in the serialization format.
 +
-NOTE: In other words, used when converting Ruby objects back into the serialized format.
+NOTE: In other words, used when converting a Lutaml::Model Ruby object into the
+serialized format.
 
 Syntax:
 
@@ -5705,101 +7755,616 @@ Syntax:
 ----
 {map_command} 'format-key', to: :attribute_name, value_map: { <1>
   from: {
-    {format-missing-value-1}: {model-missing-value-1}, <2>
-    {format-missing-value-2}: {model-missing-value-2},
-    {format-missing-value-3}: {model-missing-value-3}
+    {format-missing-value-n}: {model-missing-value-n}, <2>
+    {format-missing-value-m}: {model-missing-value-m},
+    {format-missing-value-o}: {model-missing-value-o}
   },
   to: {
-    {model-missing-value-1}: {format-missing-value-1}, <3>
-    {model-missing-value-2}: {format-missing-value-2},
-    {model-missing-value-3}: {format-missing-value-3}
+    {model-missing-value-n}: {format-missing-value-n}, <3>
+    {model-missing-value-m}: {format-missing-value-m},
+    {model-missing-value-o}: {format-missing-value-o}
+  }
+}
+----
+<1> The `{map_command}` is a mapping rule with the actual command depending on
+the serialization format.
+<2> In the `from` mapping, the keys are the missing value types in the
+serialization format.
+<3> In the `to` mapping, the keys are the missing value types in the LutaML
+Model.
+
+The missing value type mapping differs per serialization format,
+as serialization formats may not fully support all missing value types.
+
+The availability of `from` and `to` keys and values depend on the types of
+missing values supported by that particular serialization format.
+
+The available values for `from` and `to` for serialization formats
+are presented below, where the allowed values are to be used in the direction
+of the format. That means if the format supports `:empty`, it can be used
+as a key in `from:` direction, and the value in the `to:` direction (see `{format-missing-value-n}`) in the syntax.
+
+.Available missing value types in different mapping commands
+[cols="a,2a"]
+|===
+| Map command | Missing value types available (key in `from:` direction, value in the `to:` direction)
+
+| XML element `map_element` | `:empty`, `:omitted`, `:nil`
+| XML attribute `map_attribute` | `:empty`, `:omitted`
+| Hash `map`, `map_content` | `:empty`, `:omitted`, `:nil`
+| JSON `map`, `map_content` | `:empty`, `:omitted`, `:nil`
+| YAML `map`, `map_content` | `:empty`, `:omitted`, `:nil`
+| TOML `map`, `map_content` | `:empty`, `:omitted`
+
+|===
+
+
+[example]
+For instance, TOML does not support the notion of "null" and therefore the
+missing value type of `nil` cannot be used; therefore in a `from:`
+value map, it is not possible to indicate `nil: {model-missing-value}`.
+
+[example]
+====
+In an XML mapping block, it is possible to do the following.
+
+[source,ruby]
+----
+xml do
+  map_element 'status', to: :status, value_map: {
+    from: { empty: :nil, omitted: :omitted, nil: :nil },
+    to: { empty: :nil, omitted: :omitted, nil: :nil }
+  }
+end
+----
+====
+
+Each serialization format has specific behavior when handling values
+such as `empty`, `omitted`, and `nil`.
+
+Users can specify the mapping for both `from` and `to` values using the
+`value_map` option in the attribute definition.
+
+* The keys that can be used in the `from` and `to` mappings are `empty`,
+`omitted`, and `nil`.
+
+* The values in the mappings can also be `empty`, `omitted`, and `nil`.
+
+NOTE: Since `nil` is not supported in TOML, so mappings like `nil:
+{any_option}` or `{any_option}: :nil` will not work in TOML.
+
+NOTE: In a collection attribute, the values of `value_map` also depend on the
+`initialize_empty` setting, where an omitted value in the serialization format can still lead to a `nil`
+or an empty array `[]` at the attribute-level (instead of the mapping-level).
+
+
+
+===== Default value maps for serialization formats
+
+The table below describes the default `value_map` configurations for supported
+serialization formats.
+
+// TODO: Find a place to write this
+// XML Handling::
+// - `<status>new</status>` will be treated as `["new"]`.
+// - `<status>new</status><status>assigned</status>` will be treated as `["new", "assigned"]`.
+
+====== Default value map for XML element (single attribute)
+
+[source,ruby]
+----
+attribute :attr, :string
+
+xml do
+  map_element 'key', to: :attr, value_map: {
+    from: { empty: :nil, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+.Default missing value mapping configuration for single attributes in XML elements
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| XML source h| Model target
+
+.3+|`from:`
+| `empty: :nil`
+| blank XML element (`<status/>`)
+| `nil`
+
+| `omitted: :omitted`
+| absent XML element
+| omitted from the model
+
+| `nil: :nil`
+| blank XML element with attribute `xsi:nil` (`<status xsi:nil=true/>`)
+| `nil` value in the model
+
+
+h| Direction h| Map rule h| Model source h| XML target
+
+.3+|`to:`
+| `empty: :empty`
+| empty string (`""`)
+| blank XML element
+
+| `omitted: :omitted`
+| omitted in the model
+| XML element not rendered
+
+| `nil: :nil`
+| `nil` value in the model
+| blank XML element with attribute `xsi:nil` (`<status xsi:nil=true/>`)
+
+|===
+
+====== Default value map for XML element (collection attribute)
+
+[source,ruby]
+----
+attribute :attr, :string, collection: true
+
+xml do
+  map_element 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+.Default missing value mapping configuration for collection attributes in XML elements
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| XML source h| Model target
+
+.3+|`from:`
+| `empty: :nil`
+| blank XML element (`<status/>`)
+| empty array (`[]`)
+
+| `omitted: :omitted`
+| absent XML element
+| omitted from the model
+
+| `nil: :nil`
+| blank XML element with attribute `xsi:nil` (`<status xsi:nil=true/>`)
+| `nil` value in the model
+
+
+h| Direction h| Map rule h| Model source h| XML target
+
+.3+|`to:`
+| `empty: :empty`
+| empty array (`[]`)
+| blank XML element
+
+| `omitted: :omitted`
+| omitted in the model
+| XML element not rendered
+
+| `nil: :nil`
+| `nil` value in the model
+| blank XML element with attribute `xsi:nil` (`<status xsi:nil=true/>`)
+
+|===
+
+====== Default value map for XML attribute (single attribute)
+
+[source,ruby]
+----
+attribute :attr, :string
+
+xml do
+  map_attribute 'attr_name', to: :attr, value_map: {
+    from: { empty: :nil, omitted: :omitted },
+    to: { empty: :empty, nil: :empty, omitted: :omitted }
+  }
+end
+----
+
+.Default missing value mapping configuration for single attributes in XML attributes
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| XML source h| Model target
+
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :nil`
+| blank XML attribute (`status=""`)
+| `nil`
+
+| `omitted: :omitted`
+| absent XML attribute
+| omitted from the model
+
+h| Direction h| Map rule h| Model source h| XML target
+
+.3+|`to:` (target only accepts `empty` and `omitted`)
+| `empty: :empty`
+| empty string (`""`)
+| blank XML attribute (`status=""`)
+
+| `omitted: :omitted`
+| omitted in the model
+| XML attribute not rendered
+
+| `nil: :empty`
+| `nil`
+| blank XML attribute (`status=""`)
+
+|===
+
+====== Default value map for XML attribute (collection attribute)
+
+[source,ruby]
+----
+attribute :attr, :string, collection: true
+
+xml do
+  map_attribute 'attr_name', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted },
+    to: { empty: :empty, nil: :omitted, omitted: :omitted }
+  }
+end
+----
+
+.Default missing value mapping configuration for collection attributes in XML attributes
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| XML source h| Model target
+
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| blank XML attribute (`status=""`)
+| empty array (`[]`)
+
+| `omitted: :omitted`
+| absent XML attribute
+| omitted from the model
+
+h| Direction h| Map rule h| Model source h| XML target
+
+.3+|`to:` (target only accepts `empty` and `omitted`)
+| `empty: :empty`
+| empty array (`[]`)
+| blank XML attribute (`status=""`)
+
+| `omitted: :omitted`
+| omitted in the model
+| XML attribute not rendered
+
+| `nil: :omitted`
+| `nil`
+| XML attribute not rendered
+
+|===
+
+
+
+====== Default value map for YAML (single attribute)
+
+[source,ruby]
+----
+attribute :attr, :string
+
+yaml do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+.Default missing value mapping configuration for single attributes in YAML
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| XML source h| Model target
+
+.3+|`from:`
+| `empty: :empty`
+| empty string in YAML (`status:` or `status: ""`)
+| empty string (`""`)
+
+| `omitted: :omitted`
+| absent YAML key
+| omitted from the model
+
+| `nil: :nil`
+| YAML `null`
+| `nil`
+
+h| Direction h| Map rule h| Model source h| XML target
+
+.3+|`to:`
+| `empty: :empty`
+| empty string (`""`)
+| empty string in YAML (`status:`)
+
+| `omitted: :omitted`
+| omitted in the model
+| YAML key omitted
+
+| `nil: :nil`
+| `nil`
+| YAML `null`
+
+|===
+
+NOTE: In order to treat a YAML value like `status: ''` to `nil`, the mapping of
+`value_map: { from: { empty: :nil } }` can be applied.
+
+
+====== Default value map for YAML (collection attribute)
+
+[source,ruby]
+----
+attribute :attr, :string, collection: true
+
+yaml do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+.Default missing value mapping configuration for collection attributes in YAML
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| YAML source h| Model target
+
+.3+|`from:`
+| `empty: :empty`
+| empty YAML array (`status:` or `status: []`)
+| empty array (`[]`)
+
+| `omitted: :omitted`
+| absent YAML key
+| omitted from the model
+
+| `nil: :nil`
+| YAML `null`
+| `nil`
+
+h| Direction h| Map rule h| Model source h| YAML target
+
+.3+|`to:`
+| `empty: :empty`
+| empty array (`[]`)
+| empty YAML array (`status: []`)
+
+| `omitted: :omitted`
+| omitted in the model
+| YAML key omitted
+
+| `nil: :nil`
+| `nil`
+| YAML `null`
+
+|===
+
+NOTE: If the YAML key for the collection attribute is omitted, it will be treated
+as `nil` or an empty array depending on the `initialize_empty` setting.
+
+
+====== Default value map for JSON (single attribute)
+
+[source,ruby]
+----
+attribute :attr, :string
+
+json do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+.Default missing value mapping configuration for single attributes in JSON
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| JSON source h| Model target
+
+.3+|`from:`
+| `empty: :empty`
+| empty string in JSON (`"status" : ""`)
+| empty string (`""`)
+
+| `omitted: :omitted`
+| absent JSON key
+| omitted from the model
+
+| `nil: :nil`
+| JSON `null`
+| `nil`
+
+h| Direction h| Map rule h| Model source h| JSON target
+
+.3+|`to:`
+| `empty: :empty`
+| empty string (`""`)
+| empty string in JSON (`"status" : ""`)
+
+| `omitted: :omitted`
+| omitted in the model
+| JSON key omitted
+
+| `nil: :nil`
+| `nil`
+| JSON `null`
+
+|===
+
+
+
+====== Default value map for JSON (collection attribute)
+
+[source,ruby]
+----
+attribute :attr, :string, collection: true
+
+json do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
   }
-}
+end
 ----
-<1> The `{map_command}` is a mapping rule with the actual command depending on
-the serialization format.
-<2> In the `from` mapping, the keys are the missing value types in the
-serialization format.
-<3> In the `to` mapping, the keys are the missing value types in the LutaML
-Model.
 
-The missing value type mapping differs per serialization format,
-as serialization formats may not fully support all missing value types.
+.Default missing value mapping configuration for collection attributes in JSON
+[cols="a,a,a,a"]
+|===
 
-[example]
-For instance, TOML does not support the notion of "null" and therefore the
-missing value type of `nil` cannot be used; therefore in a `from:`
-value map, it is not possible to indicate `nil: {model-missing-value}`.
+h| Direction h| Map rule h| JSON source h| Model target
 
-[example]
-====
-In an XML mapping block, it is possible to do the following.
+.3+|`from:`
+| `empty: :empty`
+| empty JSON array (`"status": []`)
+| empty array (`[]`)
+
+| `omitted: :omitted`
+| absent JSON key
+| omitted from the model
+
+| `nil: :nil`
+| JSON `null`
+| `nil`
+
+h| Direction h| Map rule h| Model source h| JSON target
+
+.3+|`to:`
+| `empty: :empty`
+| empty array (`[]`)
+| empty JSON array (`"status": []`)
+
+| `omitted: :omitted`
+| omitted in the model
+| JSON key omitted
+
+| `nil: :nil`
+| `nil`
+| JSON `null`
+
+|===
+
+====== Default value map for TOML (single attribute)
+
+TOML does not support the concept of `nil` and therefore the mapping of `from:`
+direction with `nil` to will not work in TOML.
+
+The `nil` mapping is only supported in the `to:` direction (model to TOML).
 
 [source,ruby]
 ----
-xml do
-  map_element 'status', to: :status, value_map: {
-    from: { empty: :nil, omitted: :omitted, nil: :nil },
-    to: { empty: :nil, omitted: :omitted, nil: :nil }
+attribute :attr, :string
+
+toml do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted },
+    to: { empty: :empty, omitted: :omitted, nil: :omitted }
   }
 end
 ----
-====
 
-Each serialization format has specific behavior when handling values
-such as `empty`, `omitted`, and `nil`.
+.Default missing value mapping configuration for single attributes in TOML
+[cols="a,a,a,a"]
+|===
 
-Users can specify the mapping for both `from` and `to` values using the
-`value_map` option in the attribute definition.
+h| Direction h| Map rule h| TOML source h| Model target
 
-* The keys that can be used in the `from` and `to` mappings are `empty`,
-`omitted`, and `nil`.
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty string in TOML (`[status]` with no value)
+| empty string (`""`)
 
-* The values in the mappings can also be `empty`, `omitted`, and `nil`.
+| `omitted: :omitted`
+| absent TOML key
+| omitted from the model
 
-NOTE: Since `nil` is not supported in TOML, so mappings like `nil:
-{any_option}` or `{any_option}: :nil` will not work in TOML.
+h| Direction h| Map rule h| Model source h| TOML target
 
-The table below describes the default `value_map` configurations for supported
-serialization formats.
+.3+|`to:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty string (`""`)
+| empty string in TOML (`[status]` with no value)
+
+| `omitted: :omitted`
+| omitted in the model
+| TOML key omitted
+
+| `nil: :omitted`
+| `nil`
+| TOML key omitted
+
+|===
+
+
+
+====== Default value map for TOML (collection attribute)
+
+TOML does not support the concept of `nil` and therefore the mapping of `from:`
+direction with `nil` to will not work in TOML.
+
+The `nil` mapping is only supported in the `to:` direction (model to TOML).
+
+[source,ruby]
+----
+attribute :attr, :string, collection: true
+
+toml do
+  map 'key', to: :attr, value_map: {
+    from: { empty: :empty, omitted: :omitted },
+    to: { empty: :empty, omitted: :omitted, nil: :omitted }
+  }
+end
+----
 
-.Default missing value mapping configuration for single attribute to serialization formats
-[cols="1,1,1,1", options="header"]
+.Default missing value mapping configuration for collection attributes in TOML
+[cols="a,a,a,a"]
 |===
-| Serialization format | `from` value | `to` value | Description
 
-.3+| XML (supports all 3 types)
-| `empty`   | `nil`     |
-* Element: An empty value in the model is treated as an element with attribute `xsi:nil` during serialization.
-* Attribute: An empty value in the model is treated as an empty string in the attribute.
+h| Direction h| Map rule h| TOML source h| Model target
 
-| `omitted` | `omitted` |
-* Element: If the value is omitted in the model, the element is omitted from the XML output.
-* Attribute: If the value is omitted in the model, the attribute is omitted from the XML output.
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty TOML array (`[status]` with no value)
+| empty array (`[]`)
 
-| `nil`     | `nil`     |
-* Element: A `nil` value in the model is serialized as an element with attribute `xsi:nil`.
-* Attribute: A `nil` value in the model is treated as an empty string in the attribute.
+| `omitted: :omitted`
+| absent TOML key
+| omitted from the model
 
-.3+| YAML (supports all 3 types)
-| `empty`   | `empty`   | An empty string (`""`) in the model is deserialized as `empty` (an empty YAML string).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the YAML output.
-| `nil`     | `nil`     | A `nil` value in the model is serialized as YAML `null`.
+h| Direction h| Map rule h| Model source h| TOML target
 
-.3+| JSON (supports all 3 types)
-| `empty`   | `empty`   | An empty string (`""`) in the model is serialized as `empty` (an empty JSON string).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the JSON output.
-| `nil`     | `nil`     | A `nil` value in the model is serialized as JSON `null`.
+.3+|`to:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty array (`[]`)
+| empty TOML array (`[status]` with no value)
 
-.3+| TOML (does not support `nil`)
-| `empty`   | `empty`   | An empty string (`""`) in the model is serialized as `empty` (an empty TOML string).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the TOML output.
-| `nil`     | `omitted` | In TOML, `nil` is represented as `omitted` due to TOML limitations.
+| `omitted: :omitted`
+| omitted in the model
+| TOML key omitted
+
+| `nil: :omitted`
+| `nil`
+| TOML key omitted
 
 |===
 
 
-The `value_map` option can be defined for each serialization format as follows.
+
+===== Replacing missing values type mapping with `value_map`
+
+The `value_map` option can be defined to meticulously map for each serialization
+format as follows.
 
 [example]
 ====
@@ -5816,7 +8381,7 @@ class ExampleClass < Lutaml::Model::Serializable
     }
   end
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | toml | key_value do
     map 'status', to: :status, value_map: {
       from: { empty: :nil, omitted: :omitted, nil: :nil },
       to: { empty: :nil, omitted: :omitted, nil: :nil }
@@ -5857,57 +8422,6 @@ When defining an attribute with `collection: true`, the attribute will behave as
 attribute :status, :string, collection: true
 ----
 
-- **XML Handling**:
-  - `<status />` will be treated as `[]` (an empty array).
-  - `<status>new</status>` will be treated as `["new"]`.
-  - `<status>new</status><status>assigned</status>` will be treated as `["new", "assigned"]`.
-
-- **YAML Handling**:
-  - A value like `status: ''` in YAML will be deserialized as `nil` when `value_map: { from: { empty: :nil } }` is applied.
-  - If the collection is omitted, it will be initialized as `nil` or an empty array depending on the `initialize_empty` setting.
-
-- **JSON Handling**:
-  - A `status: []` in the serialized output will correspond to an empty array when `value_map: { from: { empty: :empty } }` is applied.
-
-- **TOML Handling**:
-  - TOML treats empty collections similarly to other formats, but `nil` values are not supported so we can not read or write nil values in TOML.
-
-.Default missing value mapping configuration for collection attributes to serialization formats
-[cols="1,1,1,1", options="header"]
-|===
-| Serialization format | `from` value | `to` value | Description
-
-.3+| XML (supports all 3 types)
-| `empty`   | `empty`     |
-* Element: An empty array (`[]`) in the model is treated a blank element (`<x/>`)
-* Attribute: An empty array (`[]`) in the model is treated as an empty string in the attribute.
-
-| `omitted` | `omitted` |
-* Element: If the value is omitted in the model, the element is omitted from the XML output.
-* Attribute: If the value is omitted in the model, the attribute is omitted from the XML output.
-
-| `nil`     | `nil`     |
-* Element: A `nil` value in the model is serialized as an element with attribute `xsi:nil`.
-* Attribute: A `nil` value in the model is treated as an empty string in the attribute.
-
-.3+| YAML (supports all 3 types)
-| `empty`   | `empty`   | An empty array (`[]`) in the model is deserialized as `empty` (an empty YAML array).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the YAML output.
-| `nil`     | `nil`     | A `nil` value in the model is serialized as YAML `null`.
-
-.3+| JSON (supports all 3 types)
-| `empty`   | `empty`   | An empty array (`[]`) in the model is serialized as `empty` (an empty JSON array).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the JSON output.
-| `nil`     | `nil`     | A `nil` value in the model is serialized as JSON `null`.
-
-.3+| TOML (does not support `nil`)
-| `empty`   | `empty`   | An empty array (`[]`) in the model is serialized as `empty` (an empty TOML array).
-| `omitted` | `omitted` | If the value is omitted in the model, the key is omitted from the TOML output.
-| `nil`     | `omitted` | In TOML, `nil` is represented as `omitted` due to TOML limitations.
-
-|===
-
-
 Here's an example of how you can use the `value_map` with a collection attribute.
 
 .Using `value_map` with a collection attribute
@@ -5925,12 +8439,19 @@ class ExampleClass < Lutaml::Model::Serializable
     }
   end
 
-  json | yaml | toml | key_value do
+  hsh | json | yaml | key_value do
     map 'status', to: :status, value_map: {
       from: { empty: :nil, omitted: :omitted, nil: :nil },
       to: { empty: :nil, omitted: :omitted, nil: :nil }
     }
   end
+
+  toml do
+    map 'status', to: :status, value_map: {
+      from: { empty: :nil, omitted: :omitted },
+      to: { empty: :nil, omitted: :omitted, nil: :omitted }
+    }
+  end
 end
 
 yaml = <<~YAML
@@ -5943,9 +8464,9 @@ y = ExampleClass.from_yaml(yaml)
 ----
 ====
 
-TODO: Need to improve this example.
+// TODO: Need to improve this example.
 
-==== Specific overrides of value map
+==== Specific overrides of value map (`render_*` and `treat_*`)
 
 ===== General
 
@@ -5982,6 +8503,52 @@ missing value types into the model.
 `{format-value}`::: specifies the missing value type in the serialization format.
 `{model-value}`::: specifies the missing value type in the LutaML Model.
 
+In effect, the default `value_map` is overriden by the `:render_*` and `:treat_*`
+directives.
+
+[example]
+====
+Given the default mapping for an XML element, the `:render_*` and `:treat_*`
+options can be used to selectively override behavior.
+
+[source,ruby]
+----
+xml do
+  map_element 'key', to: :attr, value_map: {
+    from: { empty: :nil, omitted: :omitted, nil: :nil },
+    to: { empty: :empty, omitted: :omitted, nil: :nil }
+  }
+end
+----
+
+By changing to this:
+
+[source,ruby]
+----
+xml do
+  map_element 'key', to: :attr,
+    render_nil: :as_empty, <1>
+    treat_omitted: :as_nil <2>
+end
+----
+<1> This overrides the `to:` direction `nil: :nil` mapping.
+<2> This overrides the `from:` direction `omitted: :omitted` mapping
+
+The resulting value map would be:
+
+[source,ruby]
+----
+xml do
+  map_element 'status', to: :status, value_map: {
+    from: { empty: :nil, omitted: :omitted, nil: :empty }, <1>
+    to: { empty: :nil, omitted: :nil, nil: :nil }          <2>
+  }
+end
+----
+<1> See that `nil: :nil` is now `nil: :empty`.
+<2> See that `omitted: :omitted` is now `omitted: :nil`
+====
+
 
 ==== `render_nil`
 
@@ -6014,7 +8581,7 @@ end
 
 [source,ruby]
 ----
-json | yaml | toml do
+hsh | json | yaml | toml do
   map 'key_value_model_attribute_name', to: :name_of_attribute, render_nil: {option}
 end
 ----
@@ -6153,7 +8720,7 @@ class SomeModel < Lutaml::Model::Serializable
     map_element 'collection', to: :coll, render_nil: :as_nil
   end
 
-  json | yaml do
+  hsh | json | yaml do
     map 'collection', to: :coll, render_nil: :as_nil
   end
 end
@@ -6238,7 +8805,7 @@ end
 
 [source,ruby]
 ----
-json | yaml | toml do
+hsh | json | yaml | toml do
   map 'key_value_model_attribute_name', to: :name_of_attribute, render_empty: {option}
 end
 ----
@@ -6297,7 +8864,7 @@ class SomeModel < Lutaml::Model::Serializable
     map_element 'collection', to: :coll, render_empty: :as_nil
   end
 
-  json | yaml do
+  hsh | json | yaml do
     map 'collection', to: :coll, render_empty: :as_nil
   end
 end
@@ -6356,9 +8923,91 @@ puts SomeModel.new.to_yaml
 
 
 
-== Importing data models
+== Schema generation and import
 
-=== General
+=== Schema generation
+
+Lutaml::Model provides functionality to generate schema definitions from LutaML models. This allows you to create schemas that can be used for validation or documentation purposes.
+
+Currently, the following schema formats are supported:
+
+* JSON Schema (https://json-schema.org/understanding-json-schema/[JSON Schema])
+* YAML Schema (https://yaml.org/spec/1.2/spec.html[YAML])
+
+==== JSON Schema generation
+
+The `Lutaml::Model::Schema.to_json` method generates a JSON Schema from a LutaML model class. The generated schema includes:
+
+* Properties based on model attributes
+* Validation constraints (patterns, enumerations, etc.)
+* Support for polymorphic types
+* Support for inheritance
+* Support for choice attributes
+* Collection constraints
+
+Example:
+
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, :string
+  attribute :finish, :string
+end
+
+class Vase < Lutaml::Model::Serializable
+  attribute :height, :float
+  attribute :diameter, :float
+  attribute :glaze, Glaze
+  attribute :materials, :string, collection: true
+end
+
+# Generate JSON schema
+schema = Lutaml::Model::Schema.to_json(
+  Vase,
+  id: "https://example.com/vase.schema.json",
+  description: "A vase schema",
+  pretty: true
+)
+
+# Write to file
+File.write("vase.schema.json", schema)
+----
+
+The generated schema will include definitions for all nested models and their attributes.
+
+==== YAML Schema generation
+
+The `Lutaml::Model::Schema.to_yaml` method generates a YAML Schema from a LutaML model class. The generated schema includes the same features as the JSON Schema generation.
+
+Example:
+
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, :string
+  attribute :finish, :string
+end
+
+class Vase < Lutaml::Model::Serializable
+  attribute :height, :float
+  attribute :diameter, :float
+  attribute :glaze, Glaze
+  attribute :materials, :string, collection: true
+end
+
+# Generate YAML schema
+schema = Lutaml::Model::Schema.to_yaml(
+  Vase,
+  id: "http://example.com/schemas/vase",
+  description: "A vase schema",
+  pretty: true
+)
+
+# Write to file
+File.write("vase.schema.yaml", schema)
+----
+
+=== Importing data models
 
 Lutaml::Model provides a way to import data models defined from various formats
 into the LutaML data modeling system.
@@ -6883,57 +9532,129 @@ puts output
 ----
 ====
 
-== Adapters
+
+== Serialization adapters
 
 === General
 
-Lutaml::Model uses an adapter pattern to support multiple libraries for each
-serialization format.
+The LutaML component that serializes a model into a serialization format is
+called an adapter. A serialization format may be supported by multiple adapters.
+
+An adapter typically:
 
-Lutaml::Model supports the following serialization formats:
+* supports a specific serialization format
+* provides a set of methods to serialize and deserialize models and collections of models
+
+LutaML, out of the box, supports the following serialization formats:
 
 * XML (https://www.w3.org/TR/xmlschema-1/[W3C XML Schema (Second Edition)], XML 1.0)
 * YAML (https://yaml.org/[YAML version 1.2])
 * JSON (https://www.ecma-international.org/publications-and-standards/standards/ecma-404/[ECMA-404 The JSON Data Interchange Standard], unofficial link: https://www.json.org[JSON])
 * TOML (https://toml.io/en[TOML version 1.0])
 
-You will need to specify the configuration for the adapter you want to use. The
-easiest way is to copy and paste the following configuration into your code.
+The adapter interface is also used to support certain transformation of models
+into an "end format", which is not a serialization format. For example, the
+`Lutaml::Model::HashAdapter` is used to convert a model into a hash format
+that is not a serialization format.
+
+Users can extend LutaML by creating custom adapters for other serialization
+formats or for other data formats. The
+link:docs/custom_adapters.adoc[Custom Adapters Guide] describes this process in
+detail.
 
-The configuration is as follows:
+For certain serialization formats, LutaML provides multiple adapters to support
+different serialization libraries. Please refer to their specific sections for
+more information.
+
+
+=== Configuration
+
+==== General
+
+It is necessary to configure the adapter to be used for serialization and
+deserialization for a set of formats that the LutaML models will be transformed
+into.
+
+There are two cases where you need to define such configuration:
+
+* End-user usage of the LutaML models. This is the case where you are
+using LutaML models in your application and want to serialize them into a
+specific format. If you are a gem developer that relies on lutaml-model,
+this case does not apply to you, because the end-user of your gem should
+determine the adapter configuration.
+
+* Testing purposes, e.g. RSpec. In order to run tests that involve verifying
+correctness of serialization, it is necessary to define adapter configuration.
+
+There are two ways to specify a configuration:
+
+* by providing a predefined symbol (preferred)
+* by providing the actual adapter classes
+
+There is a default configuration for adapters for commonly used formats:
+
+* YAML: `yaml_adapter_type` is set to `:standard_yaml`
+* JSON: `json_adapter_type` is set to `:standard_json`
+* Hash: `hash_adapter_type` is set to `:standard_hash`
+* XML: not defined
+* TOML: not defined
+
+
+==== Configure adapters through symbol choices
+
+The end-user or a gem developer can copy and paste the following configuration
+into an early loading file in their application or gem.
+
+This configuration is preferred over the class choices because it is more
+concise and does not require any `require` code specific to the internals
+of the LutaML runtime implementation.
+
+Syntax:
 
 [source,ruby]
 ----
 require 'lutaml/model'
-require 'lutaml/model/xml_adapter/nokogiri_adapter'
-require 'lutaml/model/json_adapter/standard_json_adapter'
-require 'lutaml/model/toml_adapter/toml_rb_adapter'
-require 'lutaml/model/yaml_adapter/standard_yaml_adapter'
 
 Lutaml::Model::Config.configure do |config|
-  config.xml_adapter = Lutaml::Model::XmlAdapter::NokogiriAdapter
-  config.yaml_adapter = Lutaml::Model::YamlAdapter::StandardYamlAdapter
-  config.json_adapter = Lutaml::Model::JsonAdapter::StandardJsonAdapter
-  config.toml_adapter = Lutaml::Model::TomlAdapter::TomlRbAdapter
+  config.xml_adapter_type = :nokogiri # can be one of [:nokogiri, :ox, :oga]
+  config.hash_adapter_type = :standard_hash
+  config.yaml_adapter_type = :standard_yaml
+  config.json_adapter_type = :standard_json # can be one of [:standard_json, :multi_json]
+  config.toml_adapter_type = :toml_rb # can be one of [:toml_rb, :tomlib]
 end
 ----
 
-You can also provide the adapter type by using symbols like
 
+==== Configure adapters through class choices
+
+The end-uesr or a gem developer can copy and paste the following configuration
+into an early loading file in their application or gem.
+
+Only the serialization formats used will require a configuration.
+
+Syntax:
+
+[example]
+====
 [source,ruby]
 ----
 require 'lutaml/model'
+require 'lutaml/model/xml/nokogiri_adapter'
+require 'lutaml/model/hash_adapter/standard_adapter'
+require 'lutaml/model/json/standard_adapter'
+require 'lutaml/model/yaml/standard_adapter'
+require 'lutaml/model/toml/toml_rb_adapter'
 
 Lutaml::Model::Config.configure do |config|
-  config.xml_adapter_type = :nokogiri # can be one of [:nokogiri, :ox, :oga]
-  config.yaml_adapter_type = :standard_yaml
-  config.json_adapter_type = :standard_json # can be one of [:standard_json, :multi_json]
-  config.toml_adapter_type = :toml_rb # can be one of [:toml_rb, :tomlib]
+  config.xml_adapter = Lutaml::Model::Xml::NokogiriAdapter
+  config.hash_adapter = Lutaml::Model::HashAdapter::StandardAdapter
+  config.yaml_adapter = Lutaml::Model::Yaml::StandardAdapter
+  config.json_adapter = Lutaml::Model::Json::StandardAdapter
+  config.toml_adapter = Lutaml::Model::Toml::TomlRbAdapter
 end
 ----
+====
 
-NOTE: By default `yaml_adapter_type` and `json_adapter_type` are set to
-`:standard_yaml` and `:standard_json` respectively.
 
 
 === XML
@@ -6960,36 +9681,17 @@ Requires native extensions (i.e. compiled C code).
 Requires the `ox` gem.
 
 
-.Using the Nokogiri XML adapter
-[source,ruby]
-----
-require 'lutaml/model'
-
-Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/xml_adapter/nokogiri_adapter'
-  config.xml_adapter = Lutaml::Model::XmlAdapter::NokogiriAdapter
-end
-----
-
-.Using the Oga XML adapter
-[source,ruby]
-----
-require 'lutaml/model'
-
-Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/xml_adapter/oga_adapter'
-  config.xml_adapter = Lutaml::Model::XmlAdapter::OgaAdapter
-end
-----
-
-.Using the Ox XML adapter
+.Using an XML adapter
 [source,ruby]
 ----
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/xml_adapter/ox_adapter'
-  config.xml_adapter = Lutaml::Model::XmlAdapter::OxAdapter
+  config.xml_adapter = :nokogiri
+  # or
+  config.xml_adapter = :oga
+  # or
+  config.xml_adapter = :ox
 end
 ----
 
@@ -7003,19 +9705,17 @@ YAML::
 The Psych YAML parser and emitter for Ruby.
 Included in the Ruby standard library.
 
-.Using the YAML adapter
+.Using a YAML adapter
 [source,ruby]
 ----
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/yaml_adapter/standard_yaml_adapter'
-  config.yaml_adapter = Lutaml::Model::YamlAdapter::StandardYamlAdapter
+  config.yaml_adapter = :standard_yaml
 end
 ----
 
 
-
 === JSON
 
 Lutaml::Model supports the following JSON adapters:
@@ -7030,27 +9730,18 @@ MultiJson::
 A gem that provides a common interface to multiple JSON libraries.
 Requires the `multi_json` gem.
 
-.Using the JSON adapter
+.Using a JSON adapter
 [source,ruby]
 ----
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/json_adapter/standard_json_adapter'
-  config.json_adapter = Lutaml::Model::JsonAdapter::StandardJsonAdapter
+  config.json_adapter = :standard_json
+  # or
+  config.json_adapter = :multi_json
 end
 ----
 
-.Using the MultiJson adapter
-[source,ruby]
-----
-require 'lutaml/model'
-
-Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/json_adapter/multi_json_adapter'
-  config.json_adapter = Lutaml::Model::JsonAdapter::MultiJsonAdapter
-end
-----
 
 === TOML
 
@@ -7069,28 +9760,82 @@ additional features.
 Requires the `tomlib` gem.
 
 
-.Using the Toml-rb adapter
+.Using a TOML adapter
 [source,ruby]
 ----
 require 'lutaml/model'
 
 Lutaml::Model::Config.configure do |config|
-  require 'lutaml/model/toml_adapter/toml_rb_adapter'
-  config.toml_adapter = Lutaml::Model::TomlAdapter::TomlRbAdapter
+  config.toml_adapter = :toml_rb
+  # or
+  config.toml_adapter = :tomlib
 end
 ----
 
-.Using the Tomlib adapter
-[source,ruby]
-----
-require 'lutaml/model'
 
-Lutaml::Model::Config.configure do |config|
-  config.toml_adapter = Lutaml::Model::TomlAdapter::TomlibAdapter
-  require 'lutaml/model/toml_adapter/tomlib_adapter'
-end
-----
+[[custom-adapters]]
+== Custom serialization adapters
+
+Lutaml::Model provides a flexible system for creating custom adapters to handle
+different data formats.
+
+Please refer to link:docs/custom_adapters.adoc[Custom adapters] for details
+and examples.
+
+
+[[schema-generation]]
+== Schema generation
+
+Lutaml::Model provides functionality to generate schema definitions from LutaML models. This allows you to create schemas that can be used for validation or documentation purposes.
+
+Currently, the following schema formats are supported:
+
+* JSON Schema (https://json-schema.org/understanding-json-schema/[JSON Schema])
+* YAML Schema (https://yaml.org/spec/1.2/spec.html[YAML])
+* XSD (https://w3.org/TR/xmlschema-1/[XML Schema Definition Language])
+* RELAX NG (https://relaxng.org/[RELAX NG])
+
+The schema generation supports advanced features such as:
 
+* Validation constraints (patterns, enumerations, ranges)
+* Choice attributes with min/max constraints
+* Polymorphic types with oneOf validation
+* Collection constraints with minItems/maxItems
+
+Please refer to link:docs/schema_generation.adoc[Schema Generation] for details
+and examples.
+
+
+[[schema-import]]
+== Schema import
+
+Lutaml::Model provides functionality to import schema definitions into LutaML
+models. This allows you to create models from existing schema definitions.
+
+Currently, the following schema formats are supported:
+
+* XSD (https://w3.org/TR/xmlschema-1/[XML Schema Definition Language])
+* JSON/YAML Schema
+
+Please refer to link:docs/schema_import.adoc[Schema Import] for details
+and examples.
+
+
+[[custom-registers]]
+=== Custom Registers
+
+A *LutaML::Model* *Register* allows for dynamic modification and reconfiguration of model hierarchies without altering the original model definitions.
+For more information, refer to the link:docs/custom_registers.adoc[Custom Registers Guide].
+
+NOTE: Before using the `Lutaml::Model::Register` instance, make sure to register it in `Lutaml::Model::GlobalRegister`.
+
+NOTE: By default, a `default_register` with the id `:default` is created and registered in the GlobalRegister. This default register is also set in `Lutaml::Model::Config.default_register` as the default value.
+
+The default register can be set at the configuration level using the following syntax:
+
+```ruby
+  Lutaml::Model::Config.default_register = :default # the register id goes here.
+```
 
 == Comparison with Shale
 
@@ -7205,6 +9950,11 @@ data models.
 | No.
 | Lutaml::Model supports attribute extraction from key-value data models.
 
+| Register
+| Yes. Supports three types of registers(<<custom-register, read more details>>) with different types of functionalities.
+| Supports `register` functionality for *Shale::Type* classes only.
+| `Lutaml::Model` registers both `Registrable` classes and `Lutaml::Model::Type` classes, offering a more comprehensive registration system.
+
 |===