lutaml-model 0.3.9 → 0.3.11

data/README.adoc

@@ -145,6 +145,8 @@ same class and all their attributes are equal.
 
 === Supported attribute value types
 
+==== General types
+
 Lutaml::Model supports the following attribute types, they can be
 referred by a string, a symbol, or their class constant.
 
@@ -166,12 +168,11 @@ attribute :name_of_attribute, {symbol | string | class}
 | `DateTime` | `:date_time` | `Lutaml::Model::Type::DateTime` | `::DateTime`
 | `TimeWithoutDate` | `:time_without_date` | `Lutaml::Model::Type::TimeWithoutDate` | `::Time`
 | `Boolean` | `:boolean` | `Lutaml::Model::Type::Boolean` | `Boolean`
-| `Decimal` | `:decimal` | `Lutaml::Model::Type::Decimal` | `::BigDecimal`
+| `Decimal` (optional) | `:decimal` | `Lutaml::Model::Type::Decimal` | `::BigDecimal`
 | `Hash` | `:hash` | `Lutaml::Model::Type::Hash` | `::Hash`
 
 |===
 
-
 .Defining attributes with supported types via symbol, string and class
 [example]
 ====
@@ -198,17 +199,68 @@ end
 ----
 ====
 
+==== (optional) Decimal type
+
+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.
+
+This means that the following code needs to be run before using (and parsing)
+the `Decimal` type:
+
+[source,ruby]
+----
+require 'bigdecimal'
+----
+
+If the `bigdecimal` library is not loaded, usage of the `Decimal` type will
+raise a `Lutaml::Model::TypeNotSupportedError`.
+
 
 === Attribute as a collection
 
 Define attributes as collections (arrays or hashes) to store multiple values
 using the `collection` option.
 
+`collection` can be set to:
+
+`true`:::
+The attribute contains an unbounded collection of objects of the declared class.
+
+`{min}..{max}`:::
+The attribute contains a collection of objects of the declared class with a
+count within the specified range.
+If the number of objects is out of this numbered range,
+`CollectionCountOutOfRangeError` will be raised.
++
+[example]
+====
+When set to `0..1`, it means that the attribute is optional, it could be empty
+or contain one object of the declared class.
+====
++
+[example]
+====
+When set to `1..` (equivalent to `1..Infinity`), it means that the
+attribute must contain at least one object of the declared class and can contain
+any number of objects.
+====
++
+[example]
+====
+When set to 5..10` means that there is a minimum of 5 and a maximum of 10
+objects of the declared class. If the count of values for the attribute is less
+then 5 or greater then 10, the `CollectionCountOutOfRangeError` will be raised.
+====
+
+
 Syntax:
 
 [source,ruby]
 ----
 attribute :name_of_attribute, Type, collection: true
+attribute :name_of_attribute, Type, collection: {min}..{max}
+attribute :name_of_attribute, Type, collection: {min}..
 ----
 
 .Using the `collection` option to define a collection attribute
@@ -219,18 +271,27 @@ attribute :name_of_attribute, Type, collection: true
 class Studio < Lutaml::Model::Serializable
   attribute :location, :string
   attribute :potters, :string, collection: true
+  attribute :address, :string, collection: 1..2
+  attribute :hobbies, :string, collection: 0..
 end
 ----
 
 [source,ruby]
 ----
-> Studio.new.potters
+> Studio.new
+> # address count is `0`, must be between 1 and 2  (Lutaml::Model::CollectionCountOutOfRangeError)
+> Studio.new({ address: ["address 1", "address 2", "address 3"] })
+> # address count is `3`, must be between 1 and 2  (Lutaml::Model::CollectionCountOutOfRangeError)
+> Studio.new({ address: ["address 1"] }).potters
 > # []
-> Studio.new(potters: ['John Doe', 'Jane Doe']).potters
+> Studio.new({ address: ["address 1"] }).address
+> # ["address 1"]
+> Studio.new(address: ["address 1"], potters: ['John Doe', 'Jane Doe']).potters
 > # ['John Doe', 'Jane Doe']
 ----
 ====
 
+
 [[attribute-enumeration]]
 === Attribute as an enumeration
 
@@ -946,6 +1007,125 @@ end
 
 TODO: How to create mixed content from `#new`?
 
+[[xml-schema-location]]
+==== Automatic support of `xsi:schemaLocation`
+
+The
+https://www.w3.org/TR/xmlschema-1/#xsi_schemaLocation[W3C "XMLSchema-instance"]
+namespace describes a number of attributes that can be used to control the
+behavior of XML processors. One of these attributes is `xsi:schemaLocation`.
+
+The `xsi:schemaLocation` attribute locates schemas for elements and attributes
+that are in a specified namespace. Its value consists of pairs of a namespace
+URI followed by a relative or absolute URL where the schema for that namespace
+can be found.
+
+Usage of `xsi:schemaLocation` in an XML element depends on the declaration of
+the XML namespace of `xsi`, i.e.
+`xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"`. Without this namespace
+LutaML will not be able to serialize the `xsi:schemaLocation` attribute.
+
+NOTE: It is most commonly attached to the root element but can appear further
+down the tree.
+
+The following snippet shows how `xsi:schemaLocation` is used in an XML document:
+
+[source,xml]
+----
+<cera:Ceramic
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xmlns:cera="http://example.com/ceramic"
+  xmlns:clr='http://example.com/color'
+  xsi:schemaLocation=
+    "http://example.com/ceramic http://example.com/ceramic.xsd
+     http://example.com/color http://example.com/color.xsd"
+  clr:color="navy-blue">
+  <cera:Type>Porcelain</cera:Type>
+  <Glaze>Clear</Glaze>
+</cera:Ceramic>
+----
+
+LutaML::Model supports the `xsi:schemaLocation` attribute in all XML
+serializations by default, through the `schema_location` attribute on the model
+instance object.
+
+.Retrieving and setting the `xsi:schemaLocation` attribute in XML serialization
+[example]
+====
+In this example, the `xsi:schemaLocation` attribute will be automatically
+supplied without the explicit need to define in the model, and allows for
+round-trip serialization.
+
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+  attribute :color, :string
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic', 'cera'
+    map_element 'Type', to: :type, namespace: :inherit
+    map_element 'Glaze', to: :glaze
+    map_attribute 'color', to: :color, namespace: 'http://example.com/color', prefix: 'clr'
+  end
+end
+
+xml_content = <<~HERE
+<cera:Ceramic
+  xmlns:cera="http://example.com/ceramic"
+  xmlns:clr="http://example.com/color"
+  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  clr:color="navy-blue"
+  xsi:schemaLocation="
+    http://example.com/ceramic http://example.com/ceramic.xsd
+    http://example.com/color http://example.com/color.xsd
+  ">
+  <cera:Type>Porcelain</cera:Type>
+  <Glaze>Clear</Glaze>
+</cera:Ceramic>
+HERE
+----
+
+[source,ruby]
+----
+> c = Ceramic.from_xml(xml_content)
+=>
+#<Ceramic:0x00000001222bdd60
+...
+> schema_loc = c.schema_location
+#<Lutaml::Model::SchemaLocation:0x0000000122773760
+...
+> schema_loc
+=>
+#<Lutaml::Model::SchemaLocation:0x0000000122773760
+ @namespace="http://www.w3.org/2001/XMLSchema-instance",
+ @original_schema_location="http://example.com/ceramic http://example.com/ceramic.xsd http://example.com/color http://example.com/color.xsd",
+ @prefix="xsi",
+ @schema_location=
+  [#<Lutaml::Model::Location:0x00000001222bd018 @location="http://example.com/ceramic.xsd", @namespace="http://example.com/ceramic">,
+   #<Lutaml::Model::Location:0x00000001222bcfc8 @location="http://example.com/color.xsd", @namespace="http://example.com/color">]>
+> new_c = Ceramic.new(type: "Porcelain", glaze: "Clear", color: "navy-blue", schema_location: schema_loc).to_xml
+> puts new_c
+# <cera:Ceramic
+#   xmlns:cera="http://example.com/ceramic"
+#   xmlns:clr="http://example.com/color"
+#   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+#   clr:color="navy-blue"
+#   xsi:schemaLocation="
+#     http://example.com/ceramic http://example.com/ceramic.xsd
+#     http://example.com/color http://example.com/color.xsd
+#   ">
+#   <cera:Type>Porcelain</cera:Type>
+#   <cera:Glaze>Clear</cera:Glaze>
+# </cera:Ceramic>
+----
+====
+
+NOTE: For details on `xsi:schemaLocation`, please refer to the
+https://www.w3.org/TR/xmlschema-1/#xsi_schemaLocation[W3C XML standard].
+
 
 
 === Key value data models
@@ -1282,9 +1462,14 @@ NOTE: The corresponding keyword used by Shale is `receiver:` instead of
 
 ==== Attribute serialization with custom methods
 
+===== General
+
 Define custom methods for specific attribute mappings using the `with:` key for
 each serialization mapping block for `from` and `to`.
 
+
+===== XML serialization with custom methods
+
 Syntax:
 
 .XML serialization with custom methods
@@ -1306,6 +1491,81 @@ xml do
 end
 ----
 
+.Using the `with:` key to define custom serialization methods for XML
+[example]
+====
+The following class will parse the XML snippet below:
+
+[source,ruby]
+----
+class CustomCeramic < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :size, :integer
+  attribute :description, :string
+
+  xml do
+    map_element "Name", to: :name, with: { to: :name_to_xml, from: :name_from_xml }
+    map_attribute "Size", to: :size, with: { to: :size_to_xml, from: :size_from_xml }
+    map_content with: { to: :description_to_xml, from: :description_from_xml }
+  end
+
+  def name_to_xml(model, parent, doc)
+    el = doc.create_element("Name")
+    doc.add_text(el, "XML Masterpiece: #{model.name}")
+    doc.add_element(parent, el)
+  end
+
+  def name_from_xml(model, value)
+    model.name = value.sub(/^XML Masterpiece: /, "")
+  end
+
+  def size_to_xml(model, parent, doc)
+    doc.add_attribute(parent, "Size", model.size + 3)
+  end
+
+  def size_from_xml(model, value)
+    model.size = value.to_i - 3
+  end
+
+  def description_to_xml(model, parent, doc)
+    doc.add_text(parent, "XML Description: #{model.description}")
+  end
+
+  def description_from_xml(model, value)
+    model.description = value.join.strip.sub(/^XML Description: /, "")
+  end
+end
+----
+
+[source,xml]
+----
+<CustomCeramic Size="15">
+  <Name>XML Masterpiece: Vase</Name>
+  XML Description: A beautiful ceramic vase
+</CustomCeramic>
+----
+
+[source,ruby]
+----
+> CustomCeramic.from_xml(xml)
+> #<CustomCeramic:0x0000000108d0e1f8
+   @element_order=["text", "Name", "text", "Size", "text"],
+   @name="Masterpiece: Vase",
+   @ordered=nil,
+   @size=12,
+   @description="A beautiful ceramic vase",
+   @validate_on_set=false>
+> puts CustomCeramic.new(name: "Vase", size: 12, description: "A beautiful vase").to_xml
+# <CustomCeramic Size="15">
+#   <Name>XML Masterpiece: Vase</Name>
+#   XML Description: A beautiful vase
+# </CustomCeramic>
+----
+====
+
+
+===== Key-value data model serialization with custom methods
+
 .Key-value data model serialization with custom methods
 [source,ruby]
 ----
@@ -1333,12 +1593,12 @@ class CustomCeramic < Lutaml::Model::Serializable
     map 'size', to: :size
   end
 
-  def name_to_json(model, value)
-    doc["name"] = "Masterpiece: #{value}"
+  def name_to_json(model, doc)
+    doc["name"] = "Masterpiece: #{model.name}"
   end
 
-  def name_from_json(model, doc)
-    model.name = value.sub(/^JSON Masterpiece: /, '')
+  def name_from_json(model, value)
+    model.name = value.sub(/^Masterpiece: /, '')
   end
 end
 ----
@@ -1362,7 +1622,7 @@ end
 
 
 [[attribute-extraction]]
-==== Attribute extraction
+==== Attribute extraction (for key-value data models only)
 
 NOTE: This feature is for key-value data model serialization only.
 
@@ -1547,6 +1807,101 @@ In this example:
 ====
 
 
+== Validation
+
+=== General
+
+Lutaml::Model provides a way to validate data models using the `validate` and
+`validate!` methods.
+
+* The `validate` method sets an `errors` array in the model instance that
+contains all the validation errors. This method is used for checking the
+validity of the model silently.
+
+* The `validate!` method raises a `Lutaml::Model::ValidationError` that contains
+all the validation errors. This method is used for forceful validation of the
+model through raising an error.
+
+Lutaml::Model supports the following validation methods:
+
+* `collection`:: Validates collection size range.
+* `values`:: Validates the value of an attribute from a set of fixed values.
+
+[example]
+====
+The following class will validate the `degree_settings` attribute to ensure that
+it has at least one element and that the `description` attribute is one of the
+values in the set `[one, two, three]`.
+
+[source,ruby]
+----
+class Klin < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :degree_settings, :integer, collection: (1..)
+  attribute :description, :string, values: %w[one two three]
+
+  xml do
+    map_element 'name', to: :name
+    map_attribute 'degree_settings', to: :degree_settings
+  end
+end
+
+klin = Klin.new(name: "Klin", degree_settings: [100, 200, 300], description: "one")
+klin.validate
+# => []
+
+klin = Klin.new(name: "Klin", degree_settings: [], description: "four")
+klin.validate
+# => [
+#      #<Lutaml::Model::CollectionSizeError: degree_settings must have at least 1 element>,
+#      #<Lutaml::Model::ValueError: description must be one of [one, two, three]>
+#    ]
+
+e = klin.validate!
+# => Lutaml::Model::ValidationError: [
+#      degree_settings must have at least 1 element,
+#      description must be one of [one, two, three]
+#    ]
+e.errors
+# => [
+#     #<Lutaml::Model::CollectionSizeError: degree_settings must have at least 1 element>,
+#     #<Lutaml::Model::ValueError: description must be one of [one, two, three]>
+#   ]
+----
+====
+
+=== Custom validation
+
+To add custom validation, override the `validate` method in the model class.
+Additional errors should be added to the `errors` array.
+
+[example]
+====
+The following class validates the `degree_settings` attribute when the `type` is
+`glass` to ensure that the value is less than 1300.
+
+[source,ruby]
+----
+class Klin < Lutaml::Model::Serializable
+  attribute :name, :string
+  attribute :type, :string, values: %w[glass ceramic]
+  attribute :degree_settings, :integer, collection: (1..)
+
+  def validate
+    errors = super
+    if type == "glass" && degree_settings.any? { |d| d > 1300 }
+      errors << Lutaml::Model::Error.new("Degree settings for glass must be less than 1300")
+    end
+  end
+end
+
+klin = Klin.new(name: "Klin", type: "glass", degree_settings: [100, 200, 1400])
+klin.validate
+# => [#<Lutaml::Model::Error: Degree settings for glass must be less than 1300>]
+----
+====
+
+
 == Adapters
 
 === General
@@ -1735,9 +2090,9 @@ differences in implementation.
 |
 
 | Value types
-| `Lutaml::Model::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `DateTime`, `Time`, `Hash`.
+| `Lutaml::Model::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `DateTime`, `Time`, `Decimal`, `Hash`.
 | `Shale::Type` includes: `Integer`, `String`, `Float`, `Boolean`, `Date`, `Time`.
-| Lutaml::Model supports the additional value types `DateTime` and `Hash`.
+| Lutaml::Model supports additional value types `Decimal`, `DateTime` and `Hash`.
 
 | Configuration
 | `Lutaml::Model::Config`
@@ -1754,6 +2109,11 @@ differences in implementation.
 | XML, YAML, JSON, TOML, CSV
 | Lutaml::Model does not support CSV.
 
+| Validation
+| Supports collection range, fixed values, and custom validation
+| Requires implementation
+|
+
 | Adapter support
 | XML (Nokogiri, Ox, Oga), YAML, JSON (JSON, MultiJson), TOML (Toml-rb, Tomlib)
 | XML (Nokogiri, Ox), YAML, JSON (JSON, MultiJson), TOML (Toml-rb, Tomlib), CSV
@@ -1785,6 +2145,12 @@ namespace from the root element.
 | No.
 |
 
+| Support for `xsi:schemaLocation`
+| Yes. Automatically supports the <<xml-schema-location,`xsi:schemaLocation`>>
+attribute for every element.
+| Requires manual specification on every XML element that uses it.
+|
+
 4+h| Attribute features
 
 | Attribute delegation
@@ -1804,7 +2170,6 @@ data models.
 | No.
 | Lutaml::Model supports attribute extraction from key-value data models.
 
-
 |===
 
 
@@ -1857,25 +2222,26 @@ Actions:
 
 === Step 2: Replace value type definitions
 
-Value types in `Lutaml::Model` are under the `Lutaml::Model::Type` module.
+Value types in `Lutaml::Model` are under the `Lutaml::Model::Type` module,
+or use the LutaML type symbols.
 
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
-  attribute :length, Lutaml::Model::Type::Integer
-  attribute :description, Lutaml::Model::Type::String
+  attribute :length, :integer
+  attribute :description, :string
 end
 ----
 
 [NOTE]
 ====
-`Lutaml::Model` also supports specifying predefined value types as strings or
+`Lutaml::Model` supports specifying predefined value types as strings or
 symbols, which is not supported by Shale.
 
 [source,ruby]
 ----
 class Example < Lutaml::Model::Serializable
-  attribute :length, :integer
+  attribute :length, Lutaml::Model::Type::Integer
   attribute :description, "String"
 end
 ----
@@ -2112,6 +2478,6 @@ allowing you to shape and structure your data into useful forms.
 == License and Copyright
 
 This project is licensed under the BSD 2-clause License.
-See the LICENSE file for details.
+See the link:LICENSE.md[] file for details.
 
 Copyright Ribose.

data/lib/lutaml/model/attribute.rb

@@ -6,11 +6,11 @@ module Lutaml
       def initialize(name, type, options = {})
         @name = name
         @type = cast_type(type)
-
         @options = options
 
-        if collection? && !options[:default]
-          @options[:default] = -> { [] }
+        if collection?
+          validate_collection_range
+          @options[:default] = -> { [] } unless options[:default]
         end
       end
 
@@ -27,20 +27,145 @@ module Lutaml
         raise ArgumentError, "Unknown Lutaml::Model::Type: #{type}"
       end
 
+      def cast_value(value)
+        return type.cast(value) unless value.is_a?(Array)
+
+        value.map { |v| type.cast(v) }
+      end
+
+      def setter
+        :"#{@name}="
+      end
+
       def collection?
         options[:collection] || false
       end
 
+      def singular?
+        !collection?
+      end
+
       def default
-        return options[:default].call if options[:default].is_a?(Proc)
+        value = if options[:default].is_a?(Proc)
+                  options[:default].call
+                else
+                  options[:default]
+                end
 
-        options[:default]
+        cast_value(value)
       end
 
       def render_nil?
         options.fetch(:render_nil, false)
       end
 
+      def enum_values
+        @options.key?(:values) ? @options[:values] : []
+      end
+
+      # Check if the value to be assigned is valid for the attribute
+      #
+      # Currently there are 2 validations
+      #   1. Value should be from the values list if they are defined
+      #      e.g values: ["foo", "bar"] is set then any other value for this
+      #          attribute will raise `Lutaml::Model::InvalidValueError`
+      #
+      #   2. Value count should be between the collection range if defined
+      #      e.g if collection: 0..5 is set then the value greater then 5
+      #          will raise `Lutaml::Model::CollectionCountOutOfRangeError`
+      def validate_value!(value)
+        valid_value!(value)
+        valid_collection!(value)
+      end
+
+      def valid_value!(value)
+        return true if value.nil? && !collection?
+        return true if enum_values.empty?
+
+        unless valid_value?(value)
+          raise Lutaml::Model::InvalidValueError.new(name, value, enum_values)
+        end
+
+        true
+      end
+
+      def valid_value?(value)
+        return true unless options[:values]
+
+        options[:values].include?(value)
+      end
+
+      def validate_value!(value)
+        # return true if none of the validations are present
+        return true if enum_values.empty? && singular?
+
+        # Use the default value if the value is nil
+        value = default if value.nil?
+
+        valid_value!(value) && valid_collection!(value)
+      end
+
+      def validate_collection_range
+        range = @options[:collection]
+        return if range == true
+
+        unless range.is_a?(Range)
+          raise ArgumentError, "Invalid collection range: #{range}"
+        end
+
+        if range.begin.nil?
+          raise ArgumentError,
+                "Invalid collection range: #{range}. Begin must be specified."
+        end
+
+        if range.begin.negative?
+          raise ArgumentError,
+                "Invalid collection range: #{range}. Begin must be non-negative."
+        end
+
+        if range.end && range.end < range.begin
+          raise ArgumentError,
+                "Invalid collection range: #{range}. End must be greater than or equal to begin."
+        end
+      end
+
+      def valid_collection!(value)
+        return true unless collection?
+
+        # Allow nil values for collections during initialization
+        return true if value.nil?
+
+        # Allow any value for unbounded collections
+        return true if options[:collection] == true
+
+        unless value.is_a?(Array)
+          raise Lutaml::Model::CollectionCountOutOfRangeError.new(
+            name,
+            value,
+            options[:collection],
+          )
+        end
+
+        range = options[:collection]
+        return true unless range.is_a?(Range)
+
+        if range.end.nil?
+          if value.size < range.begin
+            raise Lutaml::Model::CollectionCountOutOfRangeError.new(
+              name,
+              value,
+              range,
+            )
+          end
+        elsif !range.cover?(value.size)
+          raise Lutaml::Model::CollectionCountOutOfRangeError.new(
+            name,
+            value,
+            range,
+          )
+        end
+      end
+
       def serialize(value, format, options = {})
         if value.is_a?(Array)
           value.map do |v|