lutaml-model 0.3.24 → 0.3.26

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 18b88c11cf49c7a08199273885c202ea29ebc3aa9f470d1bffc177282b1d588b
-  data.tar.gz: 75b4d90ea27a62c55ca6643a80358ab80a0d7636b4c6511ecafa526e0855f294
+  metadata.gz: 1dc709174fab4f4df2214f08b536e0b1aded39f0c9f48a18eb5a4a53da3fc4b6
+  data.tar.gz: 9eea83160b8210f84d4b2f9baf2ab577ca91d2a737eaf98b175d52385e6fb5d3
 SHA512:
-  metadata.gz: 16d82eb3101b2e22f5d2e9197d3fdea94c787675d489a4a3792e7548f4275c6c926a87cf6a6242ee4672526ba1f0d3eb26c8fd629341240d4a93ab6d614d522f
-  data.tar.gz: 1369a5abd8dd616e28b4a8c5b7db3369634bf37c701c0cca76b20182df922e18e120c754bb486745f7d47df0bff983bdf6cb2e3651713e08aebe5c1eeb87297f
+  metadata.gz: 1e75326adeb9b8804f1bcc99104707edc3656e870d16c8af22e07e32ead9f4d78cd87eb372ebb834f2a5d942d58819e0fd3800e23a8099cf951360765223cd25
+  data.tar.gz: ecc145fb2d9250cf855243c7b9cf468919f2530eed03039bd6c7a521fa534327a1a67c5348237b3d5959e20fa0fc2b2cadc87e57139f451610cd2d7d695f251b

data/.rubocop_todo.yml

@@ -1,19 +1,19 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2024-11-08 07:37:57 UTC using RuboCop version 1.66.1.
+# on 2024-11-11 10:52:30 UTC using RuboCop version 1.68.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 127
+# Offense count: 132
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, URISchemes, IgnoreCopDirectives, AllowedPatterns.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 11
+# Offense count: 12
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: enums
 Lint/ConstantDefinitionInBlock:
@@ -22,15 +22,17 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/lutaml/model/schema/relaxng_schema_spec.rb'
     - 'spec/lutaml/model/schema/xsd_schema_spec.rb'
     - 'spec/lutaml/model/schema/yaml_schema_spec.rb'
+    - 'spec/lutaml/model/type_spec.rb'
     - 'spec/lutaml/model/validation_spec.rb'
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
+    - 'lib/lutaml/model/type/float.rb'
 
-# Offense count: 38
+# Offense count: 36
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Exclude:
@@ -40,7 +42,6 @@ Metrics/AbcSize:
     - 'lib/lutaml/model/schema/relaxng_schema.rb'
     - 'lib/lutaml/model/schema/xsd_schema.rb'
     - 'lib/lutaml/model/serialize.rb'
-    - 'lib/lutaml/model/type.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
@@ -52,19 +53,19 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 47
 
-# Offense count: 27
+# Offense count: 26
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
     - 'lib/lutaml/model/comparable_model.rb'
     - 'lib/lutaml/model/serialize.rb'
-    - 'lib/lutaml/model/type.rb'
+    - 'lib/lutaml/model/type/integer.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
 
-# Offense count: 50
+# Offense count: 53
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 46
@@ -72,15 +73,16 @@ Metrics/MethodLength:
 # Offense count: 7
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
-  Max: 13
+  Max: 14
 
-# Offense count: 22
+# Offense count: 23
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Exclude:
     - 'lib/lutaml/model/attribute.rb'
     - 'lib/lutaml/model/comparable_model.rb'
     - 'lib/lutaml/model/serialize.rb'
+    - 'lib/lutaml/model/type/integer.rb'
     - 'lib/lutaml/model/xml_adapter/nokogiri_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/ox_adapter.rb'
     - 'lib/lutaml/model/xml_adapter/xml_document.rb'
@@ -95,7 +97,7 @@ RSpec/ContextWording:
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_mapping_spec.rb'
 
-# Offense count: 110
+# Offense count: 117
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 54
@@ -106,13 +108,14 @@ RSpec/IndexedLet:
   Exclude:
     - 'spec/address_spec.rb'
 
-# Offense count: 19
+# Offense count: 20
 RSpec/LeakyConstantDeclaration:
   Exclude:
     - 'spec/lutaml/model/schema/json_schema_spec.rb'
     - 'spec/lutaml/model/schema/relaxng_schema_spec.rb'
     - 'spec/lutaml/model/schema/xsd_schema_spec.rb'
     - 'spec/lutaml/model/schema/yaml_schema_spec.rb'
+    - 'spec/lutaml/model/type_spec.rb'
     - 'spec/lutaml/model/validation_spec.rb'
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
 
@@ -124,7 +127,7 @@ RSpec/MultipleDescribes:
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_adapter_spec.rb'
 
-# Offense count: 123
+# Offense count: 149
 RSpec/MultipleExpectations:
   Max: 14
 
@@ -133,24 +136,34 @@ RSpec/MultipleExpectations:
 RSpec/MultipleMemoizedHelpers:
   Max: 9
 
-# Offense count: 4
+# Offense count: 9
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
 
-# Offense count: 7
+# Offense count: 13
 RSpec/PendingWithoutReason:
   Exclude:
     - 'spec/lutaml/model/mixed_content_spec.rb'
+    - 'spec/lutaml/model/type/date_time_spec.rb'
+    - 'spec/lutaml/model/type/integer_spec.rb'
+    - 'spec/lutaml/model/type/time_spec.rb'
+    - 'spec/lutaml/model/type/time_without_date_spec.rb'
     - 'spec/lutaml/model/validation_spec.rb'
     - 'spec/lutaml/model/xml_adapter/oga_adapter_spec.rb'
     - 'spec/lutaml/model/xml_adapter/xml_namespace_spec.rb'
     - 'spec/lutaml/model/xml_adapter_spec.rb'
 
-# Offense count: 1
+# Offense count: 2
 RSpec/RemoveConst:
   Exclude:
     - 'spec/lutaml/model/type/decimal_spec.rb'
+    - 'spec/lutaml/model/type_spec.rb'
+
+# Offense count: 2
+RSpec/RepeatedExampleGroupBody:
+  Exclude:
+    - 'spec/lutaml/model/type/time_without_date_spec.rb'
 
 # Offense count: 2
 RSpec/RepeatedExampleGroupDescription:
@@ -167,6 +180,12 @@ RSpec/SpecFilePathFormat:
     - 'spec/lutaml/model/defaults_spec.rb'
     - 'spec/lutaml/model/type/decimal_spec.rb'
 
+# Offense count: 1
+# Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
+RSpec/VerifiedDoubles:
+  Exclude:
+    - 'spec/lutaml/model/type/hash_spec.rb'
+
 # Offense count: 1
 Security/CompoundHash:
   Exclude:

data/README.adoc

@@ -22,6 +22,17 @@ NOTE: Instructions on how to migrate from Shale to 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
+* 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
+
+
 == Data modeling in a nutshell
 
 Data modeling is the process of creating a data model for the data to be stored
@@ -32,16 +43,110 @@ Lutaml::Model simplifies data modeling in Ruby by allowing you to define models
 with attributes and serialize/deserialize them to/from various serialization
 formats seamlessly.
 
+The Lutaml::Model data modelling approach is as follows:
+
+.Modeling relationships of a LutaML Model
+[source]
+----
+                       Lutaml Model
+                             │
+                    Has many attributes
+                             │
+                             ▼
+                        Attribute
+                             │
+                        Has type of
+                             │
+                  ┌──────────┴──────────┐
+                  │                     │
+                Model              Value (Leaf)
+                  │                     │
+       Has many attributes    Contains one basic value
+                  │                     │
+          ┌───────┴─────┐        ┌──────┴──────┐
+          │             │        │             │
+        Model      Value (Leaf)  String       Integer
+          │                      Date         Boolean
+          │                      Time         Float
+  Has many attributes            ...          ...
+          │
+          ▼
+  (Recursive pattern continues...)
+----
+
+.Example of LutaML Model instance with assigned values
+====
+[source]
+----
+Studio (Model)
+ ├── name (Value: String) = "Pottery Studio"
+ ├── address (Model)
+ │    ├── street (Value: String) = "123 Clay St"
+ │    ├── city (Value: String) = "Ceramics City"
+ │    └── postcode (Value: String) = "12345"
+ ├── established (Value: Date) = 2020-01-01
+ └── kilns (Model)
+      ├── count (Value: Integer) = 3
+      └── temperature (Value: Float) = 1200.0
+----
+====
+
+
+.Modeling relationships of a LutaML Model to serialization models
+[source]
+----
+    Core Model                  Serialization Model
+    ==========                  ===================
+        │                           (mapping)
+        │                               │
+        ▼                               ▼
+      Model                         XML Model
+        │                               │
+  ┌─────┴─────┐                  ┌──────┴──────┐
+  │           │                  │             │
+Models   Value Types ────┬──►  Models     Value Types
+  │           │          │       │             │
+  │           │          │       │             │
+  │    ┌──────┴──┐       │  ┌────┴────┐      ┌─┴─┐
+  │    │         │       │  │         │      │   │
+  │   String  Integer    │ Element  Value  xs:string
+  │   Date    Float      │ Attribute Type  xs:date
+  │   Time    Boolean    │                 xs:boolean
+  │                      │                 xs:anyURI
+  └──────┐               │
+         │               │         JSON Model
+    Contains             │              │
+    more Models          │       ┌──────┴──────┐
+    (recursive)          │       │             │
+                         └──►  Models     Value Types
+                                 │             │
+                                 │             │
+                            ┌────┴────┐      ┌─┴─┐
+                            │         │      │   │
+                           object  array  number string
+                           value          boolean null
+----
+
+.Example of LutaML Model instance transformed into a serialization model and serialized to JSON
+====
+[source]
+----
+Studio (Core Model)          JSON Model                Serialized JSON
+    │                            │                            │
+    ▼                            ▼                            ▼
+name: "Studio 1"     ┌─► { "name": "...",         {
+address:             │     "address": {             "name": "Studio 1",
+  ├── street: "..."  │       "street": "...",       "address": {
+  └── city: "..."    │       "city": "..."    ──►     "street": "...",
+kilns:               │     },                         "city": "..."
+  ├── count: 3       │    "kilnsCount": ...,        },
+  └── temp: 1200     │    "kilnsTemp": ...          "kilnsCount": 3,
+                     └─► }                          "kilnsTemp": 1200
+                                                  }
+----
+====
 
-== Features
 
-* Define models with attributes and types
-* Serialize and deserialize models to/from 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
 
 == Installation
 
@@ -150,6 +255,8 @@ same class and all their attributes are equal.
 Lutaml::Model supports the following attribute types, they can be
 referred by a string, a symbol, or their class constant.
 
+Every type has a corresponding Ruby class and a serialization format type.
+
 Syntax:
 
 [source,ruby]
@@ -159,20 +266,20 @@ attribute :name_of_attribute, {symbol | string | class}
 
 .Mapping between Lutaml::Model::Type classes, Ruby equivalents and serialization format types
 |===
-| Lutaml::Model::Type   | Ruby Class               | XML               | JSON               | YAML        | Example Value
-
-| `:string`             | `String`                 | `xs:string`       | `string`           | `string`    | `"text"`
-| `:integer`            | `Integer`                | `xs:integer`      | `number`           | `integer`   | `42`
-| `:float`              | `Float`                  | `xs:decimal`      | `number`           | `float`     | `3.14`
-| `:boolean`            | `TrueClass`/`FalseClass` | `xs:boolean`      | `boolean`          | `boolean`   | `true/false`
-| `:date`               | `Date`                   | `xs:date`         | `string` (ISO8601) | `date`      | `"2024-01-01"`
-| `:time_without_date`  | `Time`                   | `xs:time`         | `string` (ISO8601) | `time`      | `"12:34:56"`
-| `:date_time`          | `DateTime`               | `xs:dateTime`     | `string` (ISO8601) | `timestamp` | `"2024-01-01T00:00:00Z"`
-| `:time`               | `Time`                   | `xs:dateTime`     | `string` (ISO8601) | `timestamp` | `"2024-01-01T00:00:00Z"`
-| `:decimal` (optional) | `BigDecimal`             | `xs:decimal`      | `number`           | `float`     | `123.45`
-| `:hash`               | `Hash`                   | complex element   | `object`           | `map`       | `{key: "value"}`
-| `class`               | Custom Class             | complex element   | `object`           | `map`       | `CustomObject`
-| `collection: true`    | `Array` of Type          | repeated elements | `array`            | `sequence`  | `[obj1, obj2]`
+| Lutaml::Model::Type   | Ruby class               | XML               | JSON      | YAML        | Example value
+
+| `:string`             | `String`                 | `xs:string`       | `string`  | `string`  | `"text"`
+| `:integer`            | `Integer`                | `xs:integer`      | `number`  | `integer` | `42`
+| `:float`              | `Float`                  | `xs:decimal`      | `number`  | `float`   | `3.14`
+| `:boolean`            | `TrueClass`/`FalseClass` | `xs:boolean`      | `boolean` | `boolean` | `true`, `false`
+| `:date`               | `Date`                   | `xs:date`         | `string`  | `string`  | `2024-01-01` (JSON/YAML `"2024-01-01"`)
+| `:time_without_date`  | `Time`                   | `xs:time`         | `string`  | `string`  | `"12:34:56"`
+| `:date_time`          | `DateTime`               | `xs:dateTime`     | `string`  | `string`  | `"2024-01-01T12:00:00+00:00"`
+| `:time`               | `Time`                   | `xs:dateTime`     | `string`  | `string`  | `"2024-01-01T12:00:00+00:00"`
+| `:decimal` (optional) | `BigDecimal`             | `xs:decimal`      | `number`  | `float`   | `123.45`
+| `:hash`               | `Hash`                   | complex element   | object    | map       | `{key: "value"}`
+// | `class`               | Custom class             | complex element   | object    | map       | `CustomObject`
+// | `collection: true`    | `Array` of type          | repeated elements | array     | sequence  | `[obj1, obj2]`
 // | `any`
 
 |===
@@ -204,14 +311,17 @@ end
 ----
 ====
 
-==== (optional) Decimal type
+==== Decimal type
+
+The Decimal type is an optional type that is disabled by default.
 
-The `BigDecimal` class is no longer part of the standard Ruby library from Ruby
-3.4 onwards, hence the `Decimal` type is only enabled when the `bigdecimal`
-library is loaded.
+NOTE: The reason why the Decimal type is disalbed by default is that the
+`BigDecimal` class became optional to the standard Ruby library from Ruby 3.4
+onwards. The `Decimal` type is only enabled when the `bigdecimal` library is
+loaded.
 
-This means that the following code needs to be run before using (and parsing)
-the `Decimal` type:
+The following code needs to be run before using (and parsing) the Decimal
+type:
 
 [source,ruby]
 ----
@@ -222,6 +332,142 @@ If the `bigdecimal` library is not loaded, usage of the `Decimal` type will
 raise a `Lutaml::Model::TypeNotSupportedError`.
 
 
+==== Custom type
+
+A custom class can be used as an attribute type. The custom class must inherit
+from `Lutaml::Model::Type::Value` or a class that inherits from it.
+
+A class inheriting from the `Value` class carries the attribute `value` which
+stores the one-and-only "true" value that is independent of serialization
+formats.
+
+The minimum requirement for a custom class is to implement the following
+methods:
+
+`self.cast(value)`:: Assignment of an external value to the `Value` class to be
+set as `value`. Casts the value to the custom type.
+
+`self.serialize(value)`:: Serializes the custom type to an object (e.g. a
+string). Takes the internal `value` and converts it into an output suitable for
+serialization.
+
+
+.Using a custom value type to normalize a postcode with minimal methods
+[example]
+====
+[source,ruby]
+----
+class FiveDigitPostCode < Lutaml::Model::Type::String
+  def self.cast(value)
+    value = value.to_s if value.is_a?(Integer)
+
+    unless value.is_a?(::String)
+      raise Lutaml::Model::InvalidValueError, "Invalid value for type 'FiveDigitPostCode'"
+    end
+
+    # Pad zeros to the left
+    value.rjust(5, '0')
+  end
+
+  def self.serialize(value)
+    value
+  end
+end
+
+class Studio < Lutaml::Model::Serializable
+  attribute :postcode, FiveDigitPostCode
+end
+----
+====
+
+
+==== Serialization of custom types
+
+The serialization of custom types can be made to differ per serialization format
+by defining methods in the class definitions. This requires additional methods
+than the minimum required for a custom class (i.e. `self.cast(value)` and
+`self.serialize(value)`).
+
+This is useful in the case when different serialization formats of the same
+model expect differentiated value representations.
+
+The methods that can be overridden are named:
+
+`self.from_{format}(serialized_string)`:: Deserializes a string of the
+serialization format and returns the object to be assigned to the `Value` class'
+`value`.
+
+`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`).
+
+.Using custom serialization methods to handle a high-precision date-time type
+[example]
+====
+Suppose in XML we handle a high-precision date-time type that requires custom
+serialization methods, but other formats such as JSON do not support this type.
+
+For instance, in the normal DateTime class, the serialized string is
+`2012-04-07T01:51:37+02:00`, and the high-precision format is
+`2012-04-07T01:51:37.112+02:00`.
+
+We create `HighPrecisionDateTime` class is a custom class that inherits
+from `Lutaml::Model::Type::DateTime`.
+
+[source,ruby]
+----
+class HighPrecisionDateTime < Lutaml::Model::Type::DateTime
+  # Inherit the `self.cast(value)` and `self.serialize(value)` methods
+  # from Lutaml::Model::Type::DateTime
+
+  # The format looks like this `2012-04-07T01:51:37.112+02:00`
+  def self.from_xml(xml_string)
+    ::DateTime.parse(xml_string)
+  end
+
+  # The %L adds milliseconds to the time
+  def to_xml
+    value.strftime('%Y-%m-%dT%H:%M:%S.%L%:z')
+  end
+end
+
+class Ceramic < Lutaml::Model::Serializable
+  attribute :kiln_firing_time, HighPrecisionDateTime
+  xml do
+    root 'ceramic'
+    map_element 'kilnFiringTime', to: :kiln_firing_time
+    # ...
+  end
+end
+----
+
+An XML snippet with the high-precision date-time type:
+
+[source,xml]
+----
+<ceramic>
+  <kilnFiringTime>2012-04-07T01:51:37.112+02:00</kilnFiringTime>
+  <!-- ... -->
+</ceramic>
+----
+
+When loading the XML snippet, the `HighPrecisionDateTime` class will be used to
+parse the high-precision date-time string.
+
+However, when serializing to JSON, the value will have the high-precision
+part lost due to the inability of JSON to handle high-precision date-time.
+
+[source,ruby]
+----
+> c = Ceramic.from_xml(xml)
+> #<Ceramic:0x0000000104ac7240 @kiln_firing_time=#<HighPrecisionDateTime:0x0000000104ac7240 @value=2012-04-07 01:51:37.112000000 +0200>>
+> c.to_json
+> # {"kilnFiringTime":"2012-04-07T01:51:37+02:00"}
+----
+====
+
+
 === Attribute as a collection
 
 Define attributes as collections (arrays or hashes) to store multiple values
@@ -297,8 +543,15 @@ end
 ====
 
 
+=== Attribute value validation
+
+==== General
+
+There are several mechanisms to validate attribute values in Lutaml::Model.
+
+
 [[attribute-enumeration]]
-=== Attribute as an enumeration
+==== Values of an enumeration
 
 An attribute can be defined as an enumeration by using the `values` directive.
 
@@ -395,6 +648,44 @@ acceptance of the newly updated component.
 ====
 
 
+==== String values restricted to patterns
+
+An attribute that accepts a string value accepts value validation using regular
+expressions.
+
+Syntax:
+
+[source,ruby]
+----
+attribute :name_of_attribute, :string, pattern: /regex/
+----
+
+.Using the `pattern` option to restrict the value of an attribute
+[example]
+====
+In this example, the `color` attribute takes hex color values such as `#ccddee`.
+
+A regular expression can be used to validate values assigned to the attribute.
+In this case, it is `/^#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})$/`.
+
+[source,ruby]
+----
+class Glaze < Lutaml::Model::Serializable
+  attribute :color, :string, pattern: /\A#([A-Fa-f0-9]{6}|[A-Fa-f0-9]{3})\z/
+end
+----
+
+[source,ruby]
+----
+> Glaze.new(color: '#ff0000').color
+> # "#ff0000"
+> Glaze.new(color: '#ff000').color
+> # Lutaml::Model::InvalidValueError: Invalid value for attribute 'color'
+----
+====
+
+
+
 === Attribute value default and rendering defaults
 
 Specify default values for attributes using the `default` option.
@@ -525,7 +816,8 @@ class Person < Lutaml::Model::Serializable
 end
 ----
 
-For the following xml
+For the following XML snippet:
+
 [source,xml]
 ----
 <Person>
@@ -898,6 +1190,80 @@ end
 ====
 
 
+==== CDATA nodes
+
+CDATA is an XML feature that allows the inclusion of text that may contain
+characters that are unescaped in XML.
+
+While CDATA is not preferred in XML, it is sometimes necessary to handle CDATA
+nodes for both input and output.
+
+NOTE: The W3C XML Recommendation explicitly encourages escaping characters over
+usage of CDATA.
+
+Lutaml::Model supports the handling of CDATA nodes in XML in the following
+behavior:
+
+. When an attribute contains a CDATA node with no text:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as its native type.
+
+. When an XML mapping sets `cdata: true` on `map_element` or `map_content`:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as a CDATA node.
+
+. When an XML mapping sets `cdata: false` on `map_element` or `map_content`:
+** On reading: The node (CDATA or text) is read as its value.
+** On writing: The value is written as a text node (string).
+
+
+Syntax:
+
+[source,ruby]
+----
+xml do
+  map_content to: :name_of_attribute, cdata: (true | false)
+  map_element :name, to: :name, cdata: (true | false)
+end
+----
+
+.Using `cdata` to map CDATA content
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class Example < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :description, :string
+  attribute :title, :string
+  attribute :note, :string
+
+  xml do
+    root 'example'
+    map_element :name, to: :name, cdata: true
+    map_content to: :description, cdata: true
+    map_element :title, to: :title, cdata: false
+    map_element :note, to: :note, cdata: false
+  end
+end
+----
+
+[source,xml]
+----
+<example><name><![CDATA[John]]></name><![CDATA[here is the description]]><title><![CDATA[Lutaml]]></title><note>Careful</note></example>
+----
+
+[source,ruby]
+----
+> Example.from_xml(xml)
+> #<Example:0x0000000104ac7240 @name="John" @description="here is the description" @title="Lutaml" @note="Careful">
+> Example.new(name: "John", description: "here is the description", title: "Lutaml", note: "Careful").to_xml
+> #<example><name><![CDATA[John]]></name><![CDATA[here is the description]]><title>Lutaml</title><note>Careful</note></example>
+----
+====
+
 
 ==== Example for mapping