LutaML Ruby modeller

The simplest way to define a model is to create a class that inherits from Lutaml::Model::Serializable.

The attribute class method is used to define attributes.

If the model class already has a super class that it inherits from, the model can be extended using the Lutaml::Model::Serialize module.

The restrict class method is used to update or refine the validation rules for an attribute that has already been defined. This allows you to apply additional or stricter constraints to an existing attribute without redefining it.

All options that are supported by the attribute class method are also supported by the restrict method. Any unsupported option passed to restrict will result in a Lutaml::Model::InvalidAttributeOptionsError being raised.

A polymorphic attribute is an attribute that can accept multiple types of values. This is useful when the attribute defines common characteristics and behaviors among different types.

An attribute with a defined value type also accepts values that are of a class that is a subclass of the defined type.

The assigned attribute of Type accepts polymorphic classes as long as the assigned instance is of a class that either inherits from the declared type or matches it.

A naïve polymorphic approach is to define an attribute with a superclass type and assign instances of subclasses to it.

While this approach works (somewhat) in modeling, it does not work with serialization (half) or deserialization (not at all).

The following example illustrates why such approach is naïve.

Lutaml::Model offers rich support for polymorphic attributes, through configuration at both attribute and serialization levels.

In polymorphism, there are the following components:

polymorphic attribute

the attribute that can be assigned multiple types.

polymorphic attribute class

the class that has a polymorphic attribute.

polymorphic superclass

a class assigned to a polymorphic attribute that serves as the superclass for all accepted polymorphic classes.

polymorphic subclass

a class that is a subclass of the polymorphic superclass and can be assigned to the polymorphic attribute. There are often more than 2 subclasses in a scenario since polymorphism is meant to apply to multiple types.

To utilize polymorphic attributes, modification to all of these components are necessary.

In serialized form, polymorphic classes are differentiated by an explicit "polymorphic class differentiator".

There are two basic scenarios in using polymorphic attributes:

• Scenario 1: Setting polymorphism in the polymorphic superclass:

  1. Defining the polymorphic attribute

  2. Setting the differentiator in the polymorphic superclass

  3. Mapping in the polymorphic superclass

• Scenario 2: Setting polymorphism in the individual polymorphic subclasses:

  1. Defining the polymorphic attribute

  2. Setting the differentiator in the individual polymorphic subclasses

  3. Mapping in the polymorphic attribute class and individual polymorphic subclasses

The polymorphic attribute class is a class that has a polymorphic attribute.

At this level, the polymorphic option is used to specify the types that the polymorphic attribute can accept.

1. The name of the polymorphic attribute.

2. The polymorphic superclass class.

3. Any options for the attribute.

4. The polymorphic option that determines the acceptable polymorphic subclasses, or just true.

5. The polymorphic subclasses.

The polymorphic option is an array of polymorphic subclasses that the attribute can accept.

These options enable the following scenarios.

• If the polymorphic attribute is to only contain instances of the polymorphic-superclass-class, not its subclasses, then the polymorphic option is not needed.

  In the following code, ReferenceSet has an attribute references that only accepts instances of Reference. The polymorphic option does not apply.

  class ReferenceSet < Lutaml::Model::Serializable
    attribute :references, Reference, collection: true
  end

• If the attribute (collection or not) is meant to only contain one type of polymorphic subclasses, then the polymorphic option is also not needed, because the polymorphic subclass can be stated as the attribute value type.

  In the following code, ReferenceSet has an attribute references that only accepts instances of DocumentReference, a subclass of Reference. The polymorphic option does not apply.

  class ReferenceSet < Lutaml::Model::Serializable
    attribute :references, DocumentReference, collection: true
  end

• If the attribute (collection or not) is meant to contain instances belonging to any polymorphic subclass of a defined base class, then set the polymorphic: true option.

  In the following code, ReferenceSet is a class that has a polymorphic attribute references. The references attribute can accept instances of any polymorphic subclass of the Reference base class, so polymorphic: true is set.

  class ReferenceSet < Lutaml::Model::Serializable
    attribute :references, Reference, collection: true, polymorphic: true
  end

• If the attribute (collection or not) is meant to contain instances belonging to more than one polymorphic subclass, then those acceptable polymorphic subclasses should be explicitly specified in the polymorphic: […​] option.

  In the following code, ReferenceSet is a class that has a polymorphic attribute references. The references attribute can accept instances of DocumentReference and AnchorReference, both of which are subclasses of Reference.

  class ReferenceSet < Lutaml::Model::Serializable
    attribute :references, Reference, collection: true, polymorphic: [
      DocumentReference,
      AnchorReference,
    ]
  end

You can use import_model_mappings within a sequence block to include the element mappings from another model. This is useful for composing complex XML structures from reusable model components.

The element mappings will be imported inside this specific sequence block that calls the import method, rest of the mappings like content, attributes, etc. will be inserted at the class level.

You can use import_model_attributes within a choice block to allow a model to accept one or more sets of attributes from other models, with flexible cardinality. This is especially useful when you want to allow a user to provide one or more alternative forms of information (e.g., contact methods) in your model.

For example, suppose you want a Person model that can have either an email, a phone, or both as contact information. You can define ContactEmail and ContactPhone as importable models, and then use import_model_attributes for both, inside a choice block in the Person model.

The register functionality is useful when you want to reference or reuse a model by a symbolic name (e.g., across files or in dynamic scenarios), rather than by direct class reference.

The import_model :group_of_items will behave the same as import_model GroupOfItems except the class is resolved from the provided register.

There are several mechanisms to validate attribute values in Lutaml::Model.

An attribute can be defined as an enumeration by using the values directive.

The values directive is used to define acceptable values in an attribute. If any other value is given, a Lutaml::Model::InvalidValueError will be raised.

Syntax:

The values set inside the values: option can be of any type, but they must match the type of the attribute. The values are compared using the == operator, so the type must implement the == method.

Also, If all the elements in values directive are strings then lutaml-model add some enum convenience methods, for each of the value the following three methods are added

• value1: will return value if set

• value1?: will return true if value is set, false otherwise

• value1=: will set the value of name_of_attribute equal to value1 if truthy value is given, and remove it otherwise.

The values can be Serialize objects, which are compared using the == and the hash methods through the Lutaml::Model::ComparableModel module.

Serialize provides a validate method that checks if all its attributes have valid values. This is necessary for the case when a value is valid at the component level, but not accepted at the aggregation level.

If a change has been made at the component level (a nested attribute has changed), the aggregation level needs to call the validate method to verify acceptance of the newly updated component.

An attribute that accepts a string value accepts value validation using regular expressions.

Syntax:

The instances directive defined at the Collection class level is used to define the collection attribute and the model type of the collection elements.

Syntax:

Where,

attribute

The name of the attribute that contains the collection.

ModelType

The model type of the collection elements.

The map_instances directive is only used in the key_value block.

Syntax:

Where,

attribute

The name of the attribute that contains model instances.

This directive maps individual array elements to the defined instances attribute. These are the items considered part of the Collection and reflected as Enumerable elements.

In the xml block, the map_element, map_attribute directives are used instead.

These directives map individual array elements to the defined instances attribute. These are the items considered part of the Collection and reflected as Enumerable elements.

Syntax for an element collection:

Where,

element-name

The name of the XML element of each model instance.

Syntax for an attribute collection:

Where,

attribute-name

The name of the XML attribute that contains all model instances.

TODO: This case needs to be fixed for JSON.

A root collection is a collection that is not contained within a parent collection.

Root collections only apply to key-value serialization formats. The XML format does not support root collections.

Root collections store multiple instances of the same model type at the root level. In other words, these are model instances that do not have a defined container at the level of the LutaML Model.

There are two kinds of root collections depending on the type of the instance value:

"Root value collection"

the value is a "primitive type"

"Root object collection"

the value is a "model instance"

Regardless of the type of root collection, the instance in a collection is always a LutaML model instance.

A root value collection is a collection that directly contains values of a primitive type.

Syntax:

A root object collection is a collection that directly contains model instances, each containing at least one serialized attribute.

Named collections are collections wrapped inside a name or a key. The "name" of the collection serves as the container root of its contained model instances.

The named collection setup applies to XML and key-value serialization formats.

In a named collection setup, the collection is defined as a Lutaml::Model::Collection class, and each instance is defined as a Lutaml::Model::Serializable class.

There are two kinds of named collections depending on the type of the instance value:

"Named value collection"

the value is a "primitive type"

"Named object collection"

the value is a "model instance"

Regardless of the name of root collection, the instance in a collection is always a LutaML model instance.

A named value collection is a collection that contains values of a primitive type.

Syntax:

A named collection can alternatively be implemented as a non-collection model ("Model class with an attribute") that contains the collection of instances. In this case, the attribute will be an Array object, which does not contain additional attributes and methods.

A named object collection is a collection that contains model instances, each containing at least one serialized attribute.

In key-value serialization formats, a key can be used to uniquely identify each instance. This usage allows for enforcing uniqueness in the collection.

A collection that contains keyed objects as its instances is commonly called a "keyed collection". A keyed object in a serialization format is an object identified with a unique key.

There are two kinds of keyed collections depending on the type of the keyed value:

"keyed value collection"

the value is a "primitive type"

"keyed object collection"

the value is a "model instance"

Regardless of the type of keyed collections, the instance in a collection is always a LutaML model instance.

The map_key method specifies that the unique key is to be moved into an attribute belonging to the instance model.

Syntax:

Where,

to_instance

Refers to the attribute name in the instance that contains the key.

{key_attribute}

The attribute name in the instance that contains the key.

The map_value method specifies that the value (the object referenced by the unique key) is to be moved into an attribute belonging to the instance model.

Syntax:

A keyed value collection is a collection where the keyed item in the serialization format is a primitive type (e.g. string, integer, etc.).

The instance item inside the collection is a model instance that contains both the serialized key and serialized value both as attributes inside the model.

All three map_key, map_value, and map_instances methods need to be used to define how instances are mapped in a keyed value collection.

A keyed object collection is a collection where the keyed item in the serialization format contains multiple attributes.

The instance item inside the collection is a model instance that contains the serialized key as one attribute, and the serialized value attributes are all attributes inside the model.

Both the map_key and map_instances are used to define how instances are mapped in a keyed object collection.

A nested keyed object collection is a keyed collection that contain other keyed collections. This case is simply a more complex arrangement of the principles applied to keyed object collections.

This pattern can extend to multiple levels of nesting, where each level contains a keyed object collection that can have its own key and value mappings.

Depends on whether a custom collection class is needed, the following mechanisms are available:

• When using a Lutaml::Model::Serializable class for a keyed collection, use the child_mappings option to map attributes.

• When using a Lutaml::Model::Collection class for a keyed collection, there are two options:

• use the map_key, map_value, and map_instances methods to map attributes; or

• use the root_mappings option to map attributes.

Collections implement the Ruby Enumerable interface, providing standard collection operations.

Collections allow the following sample Enumerable methods:

• each - Iterate over collection items

• map - Transform collection items

• select - Filter collection items

• find - Find items matching criteria

• reduce - Aggregate collection items

Collections can be initialized with an array of items or through individual item addition.

TODO: This case needs to be fixed.

Collections that maintain a specific ordering of elements.

Syntax:

Where,

{instances-name}

name of the instances accessor within the collection

ModelType

The model type of the collection elements.

{attribute-of-instance-or-proc}

How model instances are to be ordered by. Values supported are:

{attribute-of-instance}

Attribute name of an instance to be ordered by.

{proc}

Proc that returns a value to order by (same as sort_by), given the instance as input.

order

Order direction of the value:

:asc

Ascending order (default).

:desc

Descending order.

The root method sets the root element tag name of the XML document.

If root is not given, then the snake-cased class name will be used as the root.

Syntax:

The root element can be omitted by using the no_root method.

When no_root is used, only map_element can be used because without a root element there cannot be attributes.

Syntax:

The map_all tag in XML mapping captures and maps all content within an XML element into a single attribute in the target Ruby object.

The use case for map_all is to tell Lutaml::Model to not parse the content of the XML element at all, and instead handle it as an XML string.

This is useful in the case where the content of an XML element is not to be handled by a Lutaml::Model::Serializable object.

This feature is commonly used with custom methods or a custom model object to handle the content.

This includes:

• nested tags

• attributes

• text nodes

The map_all tag is exclusive and cannot be combined with other mappings (map_element, map_content) except for map_attribute for the same element, ensuring it captures the entire inner XML content.

Syntax:

The map_element method maps an XML element to a data model attribute.

Syntax:

If an element is mapped to a model object with the XML root tag name set, the mapped tag name will be used as the root name, overriding the root name.

The map_attribute method maps an XML attribute to a data model attribute.

Syntax:

The map_attribute method does not inherit the root element’s namespace. To specify a namespace for an attribute, please explicitly declare the namespace and prefix in the map_attribute method.

Content represents the text inside an XML element, inclusive of whitespace.

The map_content method maps an XML element’s content to a data model attribute.

Syntax:

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.

Lutaml::Model supports the handling of CDATA nodes in XML in the following behavior:

1. 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.

2. 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.

3. 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: