lutaml-model 0.7.1 → 0.7.2

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,13 @@ 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
+* Create custom adapters for additional data formats (see <<custom-adapters>>)
 
 
 == Data modeling in a nutshell
@@ -496,7 +497,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]
@@ -1051,16 +1052,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
@@ -1979,15 +1980,15 @@ For the following XML snippet:
 === General
 
 Lutaml::Model allows you to translate a data model into serialization models of
-various serialization formats including XML, JSON, YAML, and TOML.
+various serialization formats including XML, Hash, JSON, YAML, and TOML.
 
 Depending on the serialization format, different methods are supported for
 defining serialization and deserialization mappings.
 
-Serialization model mappings are defined under the `xml`, `json`, `yaml`, and
-`toml` blocks.
+Serialization model mappings are defined under the `xml`, `hsh`, `json`, `yaml`,
+and `toml` blocks.
 
-.Using the `xml`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
+.Using the `xml`, `hsh`, `json`, `yaml`, `toml` and `key_value` blocks to define serialization mappings
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
@@ -1995,6 +1996,10 @@ class Example < Lutaml::Model::Serializable
     # ...
   end
 
+  hsh do
+    # ...
+  end
+
   json do
     # ...
   end
@@ -3448,7 +3453,7 @@ This XML snippet is in UTF-8.
 
 ==== General
 
-Key-value data models like JSON, YAML, and TOML all share a similar structure
+Key-value data models like Hash, JSON, YAML, and TOML all share a similar structure
 where data is stored as key-value pairs.
 
 `Lutaml::Model` works with these formats in a similar way.
@@ -3461,7 +3466,7 @@ Syntax:
 
 [source,ruby]
 ----
-json | yaml | toml | key_value do
+hsh | json | yaml | toml | key_value do
   map 'key_value_model_attribute_name', to: :name_of_attribute
 end
 ----
@@ -3470,7 +3475,7 @@ 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.
@@ -3495,9 +3500,9 @@ class CeramicModel < Lutaml::Model::Serializable
     map :desc, to: :description
   end
 
-  # Equivalent to the JSON, YAML, and TOML mappings.
+  # Equivalent to the Hash, JSON, YAML, and TOML mappings.
   #
-  # json and yaml and toml do
+  # hsh and json and yaml and toml do
   #   map :id, to: color
   #   map :name, to: :full_name
   #   map :status, to: :current_status
@@ -3534,6 +3539,7 @@ desc: A ceramic with a navy blue color and clear glaze.
 
 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
@@ -3548,6 +3554,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 +3621,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 +3634,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 +3811,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 +3885,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 +4023,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 +4229,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 +4393,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 +4406,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>
@@ -4639,7 +4654,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 +4753,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 +5009,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 +5086,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 +5200,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 +5481,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 +5548,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 +5681,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)
+| empty value | N/A
 | non-existent value | `nil` (NilClass)
 | undefined value | No assigned value
 
 .3+| `:date`
 .3+| single
-| empty value | `Date.new(0)` (Date)
-| 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 +5736,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 +5794,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 +5811,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 +5820,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,14 +5829,14 @@ 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}
   }
 }
 ----
@@ -5726,6 +5850,29 @@ 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:`
@@ -5760,46 +5907,538 @@ Users can specify the mapping for both `from` and `to` values using the
 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.
 
-.Default missing value mapping configuration for single attribute to serialization formats
-[cols="1,1,1,1", options="header"]
+// 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"]
 |===
-| 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| 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
 
-| `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.
+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/>`)
+
+|===
 
-.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`.
+====== Default value map for XML attribute (single attribute)
 
-.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`.
+[source,ruby]
+----
+attribute :attr, :string
 
-.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.
+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
 
-The `value_map` option can be defined for each serialization format as follows.
+.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
+----
+
+.Default missing value mapping configuration for collection attributes in JSON
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| JSON source h| Model target
+
+.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]
+----
+attribute :attr, :string
+
+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 attributes in TOML
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| TOML source h| Model target
+
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty string in TOML (`[status]` with no value)
+| empty string (`""`)
+
+| `omitted: :omitted`
+| absent TOML key
+| omitted from the model
+
+h| Direction h| Map rule h| Model source h| TOML target
+
+.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 collection attributes in TOML
+[cols="a,a,a,a"]
+|===
+
+h| Direction h| Map rule h| TOML source h| Model target
+
+.2+|`from:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty TOML array (`[status]` with no value)
+| empty array (`[]`)
+
+| `omitted: :omitted`
+| absent TOML key
+| omitted from the model
+
+h| Direction h| Map rule h| Model source h| TOML target
+
+.3+|`to:` (source only supports `empty` and `omitted`)
+| `empty: :empty`
+| empty array (`[]`)
+| empty TOML array (`[status]` with no value)
+
+| `omitted: :omitted`
+| omitted in the model
+| TOML key omitted
+
+| `nil: :omitted`
+| `nil`
+| TOML key omitted
+
+|===
+
+
+
+===== 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 +6455,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 +6496,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 +6513,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 +6538,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 +6577,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 +6655,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 +6794,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 +6879,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 +6938,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
@@ -6896,6 +7537,7 @@ Lutaml::Model supports the following serialization formats:
 * 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.
@@ -6912,6 +7554,7 @@ 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
@@ -6926,6 +7569,7 @@ require 'lutaml/model'
 
 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]
@@ -7015,7 +7659,6 @@ end
 ----
 
 
-
 === JSON
 
 Lutaml::Model supports the following JSON adapters:
@@ -7091,6 +7734,11 @@ Lutaml::Model::Config.configure do |config|
 end
 ----
 
+[[custom-adapters]]
+=== Custom Adapters
+
+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]
 
 == Comparison with Shale