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.

Two objects are considered equal if they have the same class and all their attributes are equal. This behavior differs from the typical Ruby behavior, where two objects are considered equal only if they have the same object ID.

The comparison works recursively for nested objects and handles complex data structures:

The comparison safely handles circular references without infinite loops:

The ComparableModel module provides powerful diff functionality to visualize differences between objects and calculate similarity scores.

The comparison and diff functionality is particularly useful for:

• Testing: Verify model equality in specs

• Data Migration: Compare objects before/after transformation

• Auditing: Track changes to model instances

• Data Validation: Identify differences in data imports

• Debugging: Visualize object differences during development

• API Testing: Compare expected vs actual responses

A custom type is a user-defined class that extends the behavior of built-in types. A built-in type is one that is provided by Lutaml::Model, such as :string, :integer, or :date.

Lutaml::Model provides two approaches to define custom data structures:

Types

Defines primitive values that represent a basic unit of information. A type cannot be further decomposed. Inherits from Lutaml::Model::Type::Value.

Models

Defines objects composed of multiple attributes, of which each attribute can be a type or a model. Inherits from Lutaml::Model::Serializable.

The key differences are described in the table below.

Use Custom Types when:

• You need to transform or validate a single primitive value

• You want consistent behavior across multiple attributes of the same type

• You need format-specific serialization of primitive data

• You’re creating reusable value types (like currency, phone numbers, postcodes)

• The data represents a single conceptual value, even if complex internally

Use Models when:

• You need to model objects with multiple attributes

• You want to define relationships between objects

• You need complex nested structures

• The data represents a distinct entity or concept with multiple properties

• You need different serialization mappings for the same object structure

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.

Custom types can be registered for reuse across your application using symbols:

Custom types automatically handle type casting and can include validation:

You can extend existing built-in types to add custom behavior:

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. hash, json, xml, yaml, toml).

When implementing custom types:

1. Ensure you have a clear use case: Decide between using a custom type or a model based on whether you need to represent a single value or a complex structure.

2. Inherit appropriately: Use Lutaml::Model::Type::Value for completely new types, or extend built-in types like Type::String, Type::Integer for specialized behavior.

3. Implement required methods: Always implement self.cast(value) and self.serialize(value) at minimum.

4. Add validation: Use the cast method to validate and normalize input values.

5. Handle format-specific serialization: Override to_xml, to_json, etc. methods when different formats need different representations.

6. Register reusable types: Use Lutaml::Model::Type.register(:symbol, YourType) for types you’ll use across multiple models.

7. Leverage inheritance: Create type hierarchies for related but specialized types.

8. Test thoroughly: Custom types affect both parsing and serialization, so test with all formats you plan to use.

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

When deciding how to implement value transformations, consider:

Use Custom Value Type classes when:

• Bidirectional transformations are needed across formats

• Format-specific representations are required (XML wants YYYYMMDD, JSON wants DDMMYYYY)

• The logic will be reused across multiple attributes or models

• Complex parsing or calculation is involved (e.g., ISO week date calculations)

• Type safety and encapsulation are important

Use Attribute-level transform procs when:

• Same simple transformation applies to ALL serialization formats uniformly

• Logic is specific to one attribute in one model (non-reusable)

• Quick inline modification is sufficient

• No format-specific behavior is needed

Use Mapping-level transform procs when:

• Different transformation needed per serialization format

• One-off, non-reusable transformation

• Combined with attribute-level transforms for multi-stage processing

See Value Transformations Guide for complete decision matrix and examples.

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.

Lutaml::Model supports handling collections realized as XML attributes.

This feature allows you to serialize and deserialize multiple values stored in a single XML attribute, separated by a delimiter.

There are two approaches for handling delimited attribute values:

• Using the delimiter: option: provides simple splitting and joining with a fixed delimiter;

• Using the as_list: option: provides custom import and export logic.

The delimiter option is a straightforward way to handle attribute values that are delimited strings. It is ideal for simple cases where you need basic string splitting and joining with a fixed delimiter. It automatically splits the string during import and joins the array during export.

1. The delimiter used to split and join the string values.

The as_list option provides full control over how values are split during import and joined during export. This is useful when you need custom parsing logic. This allows for more complex transformations beyond simple splitting and joining that is achieved through using delimiters.

1. Custom logic to split the string into an array during import.

2. Custom logic to join the array into a string during export.

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.