© Ribose Inc. 2025
All rights reserved. Unless otherwise specified, no part of this publication may be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting on the internet or an intranet, without prior written permission. Permission can be requested from the address below.
Ribose Inc.
167-169 Great Portland Street
5th Floor
London
W1W 5PF
United Kingdom
www.ribose.com
This document specifies the collection capabilities in LutaML Model, which enable:
Definition of collections within models
Serialization of collections to different formats
Mapping of collection elements to different representations
For the purposes of this document, the following terms and definitions apply.
specialized class that defines a container for multiple instances of a model type
individual instance within a collection
rules that define how collection elements are serialized and deserialized
LutaML Model provides the Lutaml::Model::Collection class for defining collections of model instances.
Defined at the class level.
Defines the collection attribute and the model type of the collection elements.
Defined within the key_value block. In the xml block, the map_attribute and map_element directives are used instead.
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. The map_instances directive is only used in the key_value block.
These are simple collections store multiple instances of the same model type, placed at the root level of the serialization format.
Syntax:
Named collections are collections wrapped inside a name or a key.
Syntax:
A direct element collection can be alternatively modeled as a “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.
Collections can be nested within other models and define their own serialization rules.
Keyed collections store instances with unique keys.
Keyed collections were previously handled throughCollection with keyed elements (keyed collection). However, this new mechanism is much easier to understand.
In key-value serialization formats, a key can be used to uniquely identify each
instance. This usage allows for enforcing uniqueness in the collection. The concept of keyed collections does not typically apply to XML collections.
There are two types of values in a keyed collection:
When the value is a “model instance”. This is called the “keyed model collection”. Refer to
When the value is a “primitive type”. This is called the “keyed value collection”. Refer to
The mechanism for defining keyed collections is slightly different for both types.
The map_key method specifies that the unique key is to be moved into an attribute belonging to the instance model.
Syntax:
Where,
Refers to the attribute name in the instance that contains the key.
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:
Where,
The operation to be performed on the key-referenced value. Accepts the following values.
Each value includes multiple attributes. Map all those attributes into one attribute belonging to the instance model.
Each value is of a primitive type. Map that primitive type value into an attribute belonging to the instance model.
The attribute name in the instance that will contain the value.
In keyed model collections, the collection contains multiple model instances. Within the collection, the unique key identifies individual models.
This can be thought as the case where the unique key is moved into the model instance as a model attribute.
Here we only need the map_key method to define the key attribute in the instance.
Syntax:
The :key_attribute is the attribute name inside the ModelType used to uniquely identify each instance.
The :items attribute is the collection attribute containing the instances.
A keyed value collection is a collection of primitive values (not models) that are keyed.
Here we need to use both map_key and map_value methods to define the key attribute in the instance.
Syntax:
The :key_attribute is the attribute name inside the ModelType used to uniquely identify each instance.
The :value_attribute is the attribute name inside the ModelType used to uniquely identify each instance.
The :items attribute is the collection attribute containing the instances.
Collections support multiple serialization formats through format-specific mapping rules.
XML serialization defines how collection elements are represented in XML.
The xml block is used to define XML serialization rules for the collection.
In a collection, the following directives are available:
root — Specifies the XML container element name
no_root — Disables the root element for the collection
map_element — Specifies how individual elements are represented
map_attribute — Maps an attribute to the XML output
map_instances — Maps the collection instances to the XML output
The root directive specifies the XML container element name.
The map_element directive specifies how individual elements are represented.
The map_attribute directive maps an attribute to the XML output.
YAML serialization defines how collection elements are represented in YAML.
Produces:
JSON serialization defines how collection elements are represented in JSON.
Produces:
Collection mapping rules determine how collection elements are serialized and deserialized.
The root element name can be overridden at the collection usage point.
Collections implement the Ruby Enumerable interface, providing standard collection operations.
Collections allows 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 define validation rules for their elements.
Syntax:
Collections can be initialized with an array of items or through individual item addition.
Collections that maintain a specific ordering of elements.
Collections can be combined using set operations to create new collections.
Syntax:
Collections inherit from Enumerable and support standard enumeration methods.
Collections can be filtered using predicate methods to create new collections.
Syntax:
Collections can be transformed using mapping methods to create new collections.
Syntax:
Collections can be transformed while maintaining their collection nature.
Syntax:
This tutorial demonstrates building a car parts database using LutaML collections, progressively adding features to show different collection capabilities.
Create a basic LutaML model
Instantiate a simple collection
Use basic enumeration methods
First, define the basic model:
Then create a simple collection:
Collections inherit from Enumerable
Collections maintain type safety through the instances declaration
Basic enumeration methods are available out of the box
Configure XML serialization
Configure YAML serialization
Understand format mapping differences
Enhance the collection with serialization rules:
Produces:
Collections can support multiple serialization formats simultaneously
Each format can have its own mapping rules
Root elements and naming can be customized per format
Implement filtering methods
Add aggregation calculations
Chain collection operations
Add operation methods to the collection:
Collection operations return new collection instances
Operations can be chained
Statistical operations are easily implemented using Enumerable methods
Create hierarchical data structures
Configure nested serialization
Handle complex data relationships
First, add a category model:
Usage:
This produces:
Collections can contain other collections
Serialization rules cascade through the hierarchy
Complex relationships can be modeled naturally
Implement unique identifiers
Convert to keyed collection
Add efficient lookup methods
Enhance the CarPart model with an identifier:
Usage:
Produces:
XML representation:
Example lookups:
Keys provide efficient lookup capabilities
Different serialization formats can represent keys differently
Keyed collections maintain referential integrity
This tutorial demonstrated:
Basic collection creation and usage
Multiple serialization format support
Collection operations and aggregation
Nested collection hierarchies
Keyed collection lookup patterns
The progression from simple to complex features shows how LutaML collections can be used to build sophisticated data management systems.
There are no normative references in this document.