lutaml-model 0.3.8 → 0.3.10

data/README.adoc

@@ -204,11 +204,45 @@ end
 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 +253,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
 
@@ -652,6 +695,7 @@ end
 
 ==== Namespaces
 
+[[root-namespace]]
 ===== Namespace at root
 
 The `namespace` method in the `xml` block sets the namespace for the root
@@ -659,6 +703,7 @@ element.
 
 Syntax:
 
+.Setting default namespace at the root element
 [source,ruby]
 ----
 xml do
@@ -666,6 +711,15 @@ xml do
 end
 ----
 
+.Setting a prefixed namespace at the root element
+[source,ruby]
+----
+xml do
+  namespace 'http://example.com/namespace', 'prefix'
+end
+----
+
+
 .Using the `namespace` method to set the namespace for the root element
 [example]
 ====
@@ -698,10 +752,43 @@ end
 ----
 ====
 
+.Using the `namespace` method to set a prefixed namespace for the root element
+[example]
+====
+[source,ruby]
+----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic', 'cer'
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze
+  end
+end
+----
+
+[source,xml]
+----
+<cer:Ceramic xmlns='http://example.com/ceramic'><cer:Type>Porcelain</cer:Type><cer:Glaze>Clear</cer:Glaze></cer:Ceramic>
+----
+
+[source,ruby]
+----
+> Ceramic.from_xml(xml_file)
+> #<Ceramic:0x0000000104ac7240 @type="Porcelain", @glaze="Clear">
+> Ceramic.new(type: "Porcelain", glaze: "Clear").to_xml
+> #<cer:Ceramic xmlns="http://example.com/ceramic"><cer:Type>Porcelain</cer:Type><cer:Glaze>Clear</cer:Glaze></cer:Ceramic>
+----
+====
+
+
 ===== Namespace on attribute
 
-If the namespace is defined on an XML attribute, then that will be given
-priority over the one defined in the class.
+If the namespace is defined on a model attribute that already has a namespace,
+the mapped namespace will be given priority over the one defined in the class.
 
 Syntax:
 
@@ -725,6 +812,19 @@ In this example, `glz` will be used for `Glaze` if it is added inside the
 
 [source,ruby]
 ----
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, Glaze
+
+  xml do
+    root 'Ceramic'
+    namespace 'http://example.com/ceramic'
+
+    map_element 'Type', to: :type
+    map_element 'Glaze', to: :glaze, namespace: 'http://example.com/glaze', prefix: "glz"
+  end
+end
+
 class Glaze < Lutaml::Model::Serializable
   attribute :color, :string
   attribute :temperature, :integer
@@ -737,18 +837,6 @@ class Glaze < Lutaml::Model::Serializable
     map_element 'temperature', to: :temperature
   end
 end
-
-class Ceramic < Lutaml::Model::Serializable
-  attribute :type, :string
-  attribute :glaze, Glaze
-
-  xml do
-    root 'Ceramic'
-    map_element 'Type', to: :type
-    map_element 'Glaze', to: :glaze, namespace: 'http://example.com/glaze', prefix: "glz"
-    map_attribute 'xmlns', to: :namespace, namespace: 'http://example.com/ceramic'
-  end
-end
 ----
 
 [source,xml]
@@ -764,6 +852,11 @@ end
 
 [source,ruby]
 ----
+> # Using the original Glaze class namespace
+> Glaze.new(color: "Clear", temperature: 1050).to_xml
+> #<glaze:Glaze xmlns="http://example.com/old_glaze"><color>Clear</color><temperature>1050</temperature></glaze:Glaze>
+
+> # Using the Ceramic class namespace for Glaze
 > Ceramic.from_xml(xml_file)
 > #<Ceramic:0x0000000104ac7240 @type="Porcelain", @glaze=#<Glaze:0x0000000104ac7240 @color="Clear", @temperature=1050>>
 > Ceramic.new(type: "Porcelain", glaze: Glaze.new(color: "Clear", temperature: 1050)).to_xml
@@ -800,7 +893,7 @@ class Ceramic < Lutaml::Model::Serializable
 
   xml do
     root 'Ceramic'
-    namespace 'http://example.com/ceramic', prefix: 'cera'
+    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'
@@ -810,13 +903,13 @@ end
 
 [source,xml]
 ----
-<Ceramic
+<cera:Ceramic
   xmlns:cera='http://example.com/ceramic'
   xmlns:clr='http://example.com/color'
   clr:color="navy-blue">
   <cera:Type>Porcelain</cera:Type>
   <Glaze>Clear</Glaze>
-</Ceramic>
+</cera:Ceramic>
 ----
 
 [source,ruby]
@@ -824,20 +917,18 @@ end
 > Ceramic.from_xml(xml_file)
 > #<Ceramic:0x0000000104ac7240 @type="Porcelain", @glaze="Clear", @color="navy-blue">
 > Ceramic.new(type: "Porcelain", glaze: "Clear", color: "navy-blue").to_xml
-> #<Ceramic xmlns:cera="http://example.com/ceramic"
+> #<cera:Ceramic xmlns:cera="http://example.com/ceramic"
   # xmlns:clr='http://example.com/color'
   # clr:color="navy-blue">
   #  <cera:Type>Porcelain</cera:Type>
   #  <Glaze>Clear</Glaze>
-  # </Ceramic>
+  # </cera:Ceramic>
 ----
 ====
 
 [[mixed-content]]
 ==== Mixed content
 
-===== General
-
 In XML there can be tags that contain content mixed with other tags and where
 whitespace is significant, such as to represent rich text.
 
@@ -857,9 +948,8 @@ To map this to Lutaml::Model we can use the `mixed` option in either way:
 NOTE: This feature is not supported by Shale.
 
 
-===== Specifying the `mixed` option at `root`
-
-This will always treat the content of the element itself as mixed content.
+To specify mixed content, the `mixed: true` option needs to be set at the
+`xml` block's `root` method.
 
 Syntax:
 
@@ -876,7 +966,7 @@ end
 [source,ruby]
 ----
 class Paragraph < Lutaml::Model::Serializable
-  attribute :bold, :string
+  attribute :bold, :string, collection: true # allows multiple bold tags
   attribute :italic, :string
 
   xml do
@@ -900,57 +990,125 @@ end
 TODO: How to create mixed content from `#new`?
 
 
-===== Specifying the `mixed` option when referencing a model
+==== Automatic support of `xsi:schemaLocation`
 
-This will only treat the content of the referenced model as mixed content if the
-`mixed: true` is added when referencing it.
+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`.
 
-Syntax:
+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.
 
-[source,ruby]
+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]
 ----
-xml do
-  map_element 'xml_element_name', to: :name_of_attribute, mixed: true
-end
+<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>
 ----
 
-.Applying `mixed` to treat an inner element as mixed content
+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 Paragraph < Lutaml::Model::Serializable
-  attribute :bold, :string
-  attribute :italic, :string
-
-  xml do
-    root 'p'
-
-    map_element 'bold', to: :bold
-    map_element 'i', to: :italic
-  end
-end
-
-class Description < Lutaml::Model::Serializable
-  attribute :paragraph, Paragraph
+class Ceramic < Lutaml::Model::Serializable
+  attribute :type, :string
+  attribute :glaze, :string
+  attribute :color, :string
 
   xml do
-    root 'description'
-
-    map_element 'p', to: :paragraph, mixed: true
+    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
-----
 
-[source,ruby]
-----
-> Description.from_xml("<description><p>My name is <bold>John Doe</bold>, and I'm <i>28</i> years old</p></description>")
-> #<Description:0x0000000104ac7240 @paragraph=#<Paragraph:0x0000000104ac7240 @bold="John Doe", @italic="28">>
-> Description.new(paragraph: Paragraph.new(bold: "John Doe", italic: "28")).to_xml
-> #<description><p>My name is <bold>John Doe</bold>, and I'm <i>28</i> years old</p></description>
+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
 
@@ -1337,12 +1495,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
 ----
@@ -1551,6 +1709,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
@@ -1579,7 +1832,7 @@ Lutaml::Model::Config.configure do |config|
 end
 ----
 
-You can also provide the adapter type by using symbols like 
+You can also provide the adapter type by using symbols like
 
 [source,ruby]
 ----
@@ -1765,6 +2018,11 @@ differences in implementation.
 
 4+h| XML features
 
+| <<root-namespace,XML default namespace>>
+| Yes. Supports `<root xmlns='http://example.com'>` through the `namespace` option without prefix.
+| No. Only supports `<root xmlns:prefix='http://example.com'>`.
+|
+
 | XML mixed content support
 | Yes. Supports the following kind of XML through <<mixed-content,mixed content>> support.
 

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
 
@@ -31,6 +31,10 @@ module Lutaml
         options[:collection] || false
       end
 
+      def singular?
+        !collection?
+      end
+
       def default
         return options[:default].call if options[:default].is_a?(Proc)
 
@@ -41,6 +45,113 @@ module Lutaml
         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|