lutaml-model 0.7.3 → 0.7.6

data/README.adoc

@@ -39,7 +39,11 @@ Lutaml::Model are provided in <<migrate-from-shale>>.
 * 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
@@ -270,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
@@ -377,7 +397,7 @@ same class and all their attributes are equal.
 > # true
 ----
 
-
+[[value-definition]]
 == Value types
 
 === General types
@@ -565,6 +585,7 @@ part lost due to the inability of JSON to handle high-precision date-time.
 ====
 
 
+[[attribute-definition]]
 == Attributes
 
 
@@ -616,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
@@ -821,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
@@ -864,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.
@@ -1485,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:
 
@@ -1573,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
@@ -1629,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
@@ -1660,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
@@ -1973,22 +2224,1322 @@ For the following XML snippet:
     @name="John Doe",
     @ordered=nil>
 ----
-====
+====
+
+
+== Collections
+
+=== General
+
+Collections are used to represent a contained group of multiple instances of models.
+
+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.
+
+Models in a collection may be:
+
+* constrained to be of a single kind;
+
+* constrained to be of multiple kinds sharing common characteristics;
+
+* unbounded of any kind.
+
+LutaML Model provides the `Lutaml::Model::Collection` class for defining
+collections of model instances.
+
+=== 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,
+
+`attribute`:: The name of the attribute that contains the collection.
+`ModelType`:: The model type of the collection elements.
+
+
+==== Mapping instances: key-value formats only
+
+The `map_instances` directive is only used in the `key_value` block.
+
+Syntax:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
+
+  key_value do
+    map_instances to: {attribute}
+  end
+end
+----
+
+Where,
+
+`attribute`:: The name of the attribute that contains model instances.
+
+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.
+
+
+==== Mapping instances: XML only
+
+In the `xml` block, the `map_element`, `map_attribute` directives are used instead.
+
+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:
+
+[source,ruby]
+----
+class MyCollection < Lutaml::Model::Collection
+  instances {attribute}, ModelType
+
+  xml do
+    map_element "element-name", to: {attribute}
+  end
+end
+----
+
+Where,
+
+`element-name`:: The name of the XML element of each model instance.
+
+
+Syntax for an attribute collection:
+
+[source,ruby]
+----
+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.
+
+
+=== Collection types
+
+A LutaML collections is used for a number of scenarios:
+
+* Root collections (for key-value formats)
+* Named collections
+* Keyed collections (for key-value formats)
+* Attribute collections
+* Nested collections
+// * Polymorphic collections
+// * Polymorphic attribute collections
+
+
+=== Root collections (key-value formats only)
+
+==== 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.
 
-== Serialization model mappings
+There are two kinds of serialization models:
 
-=== General
+* Represents a singular model (maps to a Lutaml::Model::Serializable)
+* Represents a group/collection of models (maps to Lutaml::Model::Collection)
 
-Lutaml::Model allows you to translate a data model into serialization models of
-various serialization formats including XML, Hash, JSON, YAML, and TOML.
+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.
 
-Depending on the serialization format, different methods are supported for
-defining serialization and deserialization mappings.
+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)
 
-Serialization model mappings are defined under the `xml`, `hsh`, `json`, `yaml`,
-and `toml` blocks.
 
 .Using the `xml`, `hsh`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
+[example]
+====
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
@@ -2017,6 +3568,20 @@ class Example < Lutaml::Model::Serializable
   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
@@ -2988,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`
@@ -3453,11 +5019,20 @@ This XML snippet is in UTF-8.
 
 ==== General
 
-Key-value data models like Hash, 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.
@@ -3466,11 +5041,35 @@ Syntax:
 
 [source,ruby]
 ----
-hsh | 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
 
@@ -3494,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 Hash, JSON, YAML, and TOML mappings.
-  #
-  # hsh and json and yaml and toml do
-  #   map :id, to: color
-  #   map :name, to: :full_name
-  #   map :status, to: :current_status
-  # end
 end
 ----
 
@@ -3537,13 +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:
-
-* `hsh` for the Hash format
-* `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]
@@ -4477,106 +6062,447 @@ object as the value of a designated attribute.
 ----
 ====
 
-If a specified value path is not found, the corresponding attribute in the model
-will be assigned a `nil` value.
+If a specified value path is not found, the corresponding attribute in the model
+will be assigned a `nil` value.
+
+.Attribute values set to `nil` when the `path_to_value` is not found
+[example]
+====
+In the following JSON content, the `path_to_value` of `[:extras, :sunroof]` and
+`[:extras, :drinks_cooler]` at the object `"gearbox"` would be set to `nil`.
+
+[source,json]
+----
+{
+  "components": {
+    "engine": {
+      "manufacturer": "Ford",
+      "extras": {
+        "sunroof": true,
+        "drinks_cooler": true
+      }
+    },
+    "gearbox": {
+      "manufacturer": "Toyota"
+    }
+  }
+}
+----
+====
+
+
+.Using the `child_mappings` option to extract values from a key-value data model
+[example]
+====
+The following JSON contains 2 keys in schema named `foo` and `bar`.
+
+[source,json]
+----
+{
+  "schemas": {
+    "foo": { <1>
+      "path": { <2>
+        "link": "link one",
+        "name": "one"
+      }
+    },
+    "bar": { <1>
+      "path": { <2>
+        "link": "link two",
+        "name": "two"
+      }
+    }
+  }
+}
+----
+<1> The keys `foo` and `bar` are to be mapped to the `id` attribute.
+<2> The nested `path.link` and `path.name` keys are used as the `link` and
+`name` attributes, respectively.
+
+A model can be defined for this JSON as follows:
+
+[source,ruby]
+----
+class Schema < Lutaml::Model::Serializable
+  attribute :id, :string
+  attribute :link, :string
+  attribute :name, :string
+end
+
+class ChildMappingClass < Lutaml::Model::Serializable
+  attribute :schemas, Schema, collection: true
+
+  json do
+    map "schemas", to: :schemas,
+                   child_mappings: {
+                     id: :key,
+                     link: %i[path link],
+                     name: %i[path name],
+                   }
+  end
+end
+----
+
+The output becomes:
+
+[source,ruby]
+----
+> ChildMappingClass.from_json(json)
+> #<ChildMappingClass:0x0000000104ac7240
+ @schemas=
+  [#<Schema:0x0000000104ac6e30 @id="foo", @link="link one", @name="one">,
+   #<Schema:0x0000000104ac58f0 @id="bar", @link="link two", @name="two">]>
+> ChildMappingClass.new(schemas: [Schema.new(id: "foo", link: "link one", name: "one"), Schema.new(id: "bar", link: "link two", name: "two")]).to_json
+> #{"schemas"=>{"foo"=>{"path"=>{"link"=>"link one", "name"=>"one"}}, {"bar"=>{"path"=>{"link"=>"link two", "name"=>"two"}}}}}
+----
+
+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">
+#     ]>
+----
+====
+
 
-.Attribute values set to `nil` when the `path_to_value` is not found
-[example]
-====
-In the following JSON content, the `path_to_value` of `[:extras, :sunroof]` and
-`[:extras, :drinks_cooler]` at the object `"gearbox"` would be set to `nil`.
+==== YAML Stream
 
-[source,json]
-----
-{
-  "components": {
-    "engine": {
-      "manufacturer": "Ford",
-      "extras": {
-        "sunroof": true,
-        "drinks_cooler": true
-      }
-    },
-    "gearbox": {
-      "manufacturer": "Toyota"
-    }
-  }
-}
-----
-====
+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.
 
-.Using the `child_mappings` option to extract values from a key-value data model
+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]
 ====
-The following JSON contains 2 keys in schema named `foo` and `bar`.
-
-[source,json]
-----
-{
-  "schemas": {
-    "foo": { <1>
-      "path": { <2>
-        "link": "link one",
-        "name": "one"
-      }
-    },
-    "bar": { <1>
-      "path": { <2>
-        "link": "link two",
-        "name": "two"
-      }
-    }
-  }
-}
+[source,ruby]
 ----
-<1> The keys `foo` and `bar` are to be mapped to the `id` attribute.
-<2> The nested `path.link` and `path.name` keys are used as the `link` and
-`name` attributes, respectively.
+class Person
+  attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
+end
 
-A model can be defined for this JSON as follows:
+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 Schema < Lutaml::Model::Serializable
-  attribute :id, :string
-  attribute :link, :string
+class Person
   attribute :name, :string
+  attribute :age, :integer
+  attribute :id, :string
 end
 
-class ChildMappingClass < Lutaml::Model::Serializable
-  attribute :schemas, Schema, collection: true
+class Directory < Lutaml::Model::Serializeable
+  attribute :persons, Person, collection: true
 
-  json do
-    map "schemas", to: :schemas,
-                   child_mappings: {
-                     id: :key,
-                     link: %i[path link],
-                     name: %i[path name],
-                   }
+  yamls do
+    map_instances to: :persons
   end
 end
-----
 
-The output becomes:
+yamls = <<~YAMLS
+  ---
+  name: John
+  age: 30
+  id: abc-123
+  ---
+  name: Jane
+  age: 25
+  id: def-456
+YAMLS
 
-[source,ruby]
+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">
+#     ]>
 ----
-> ChildMappingClass.from_json(json)
-> #<ChildMappingClass:0x0000000104ac7240
- @schemas=
-  [#<Schema:0x0000000104ac6e30 @id="foo", @link="link one", @name="one">,
-   #<Schema:0x0000000104ac58f0 @id="bar", @link="link two", @name="two">]>
-> ChildMappingClass.new(schemas: [Schema.new(id: "foo", link: "link one", name: "one"), Schema.new(id: "bar", link: "link two", name: "two")]).to_json
-> #{"schemas"=>{"foo"=>{"path"=>{"link"=>"link one", "name"=>"one"}}, {"bar"=>{"path"=>{"link"=>"link two", "name"=>"two"}}}}}
+====
+
+.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
 
-In this example:
+  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
@@ -6997,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.
@@ -7524,60 +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 can also create custom adapters for additional data formats. See link:docs/custom_adapters.adoc[Custom Adapters Guide] for detailed information.
 
-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.
+
+For certain serialization formats, LutaML provides multiple adapters to support
+different serialization libraries. Please refer to their specific sections for
+more information.
+
 
-The configuration is as follows:
+=== 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.hash_adapter = Lutaml::Model::YamlAdapter::StandardHashAdapter
-  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.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]
+  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
@@ -7604,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
 ----
 
@@ -7647,14 +9705,13 @@ 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
 ----
 
@@ -7673,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
 
@@ -7712,33 +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 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:
 
-Lutaml::Model provides a flexible system for creating custom adapters to handle different data formats. 
-For more information See link:docs/custom_adapters.adoc[Custom Adapters Guide]
+* 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
 
@@ -7853,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.
+
 |===