© 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 transformation capabilities in LutaML Model, which enable mapping between different model representations while maintaining data integrity and structure.
It defines:
Value transformation interfaces
Model transformation patterns
Nested transformation rules
Bidirectional transformation capabilities
For the purposes of this document, the following terms and definitions apply.
operation that defines mapping rules between different model representations
model instance containing the original data to be transformed
model instance that will receive the transformed data
A LutaML model defines the internal information organization structure of an information model.
In order to allow external users to interact with the model, it is necessary to provide a way to transform the defined model into other models:
Serialization models that represent the model in a specific serialization format. e.g. JSON, XML, YAML.
Other LutaML models that represent information differently.
Information models in another modelling language that represent information differently.
The “transform” referred here is a mapping between a source LutaML model and a target LutaML model.
In LutaML, a transform is a first-order object that defines:
source model
target model
mapping between the two models
any value transforms or processing logic
A transform can be unidirectional or bidirectional.
A value transform is a transformation that operates on individual attribute values, converting from one type or format to another.
Common cases include:
Converting between different data types (e.g., string to date)
Splitting or combining values
Transforming:
source: a string date “2025-03-15”
target: a LutaML Value type “Date”.
A model transform operates on entire model structures, allowing for comprehensive mapping of various attributes and relations within the model.
Common cases include:
Converting between different model representations
Handling nested object transformations
Processing collections
Transforming:
source: a model with attributes title, author, publication_date
target: a model with attributes name, creator, date, which correspond to the source model attributes.
A source or target model here could also be a value type. For instance, extracting structured information (a model) from a string (a value type).
Transforming:
source: a string set of names "Gottlieb;von;Peter;Arnold"
target: a structured name model that contains given names (["Peter", "Arnold"]), conjunction ("von") and last name ("Gottlieb").
A transform can operate in one or both directions.
A unidirectional transform is a transformation that operates in one direction only, and cannot be reversed.
A bidirectional transform is a transformation that operates in both directions, allowing for reversible transformations.
This use case is demonstrated by the Plurimath gem’s handling of MathML conversion (plurimath/plurimath#304).
In Plurimath:
Plurimath maintains an internal math model (the Formula class) for mathematical semantics
The mml gem models the MathML language specification, and provides MathML XML serialization
When a MathML XML document is loaded, it is transformed into a Plurimath::Formula model instance in these steps:
MathML XML ⇒ The Mml LutaML model within the mml gem
The Mml LutaML model ⇒ The Plurimath::Formula LutaML model
This architecture means Plurimath::Math does not directly handle serialization, but can transform into the Mml model when serialization is needed.
When a MathML XML document is saved, the process is reversed:
The Plurimath::Formula LutaML model ⇒ The Mml LutaML model
The Mml LutaML model within the mml gem ⇒ MathML XML
A common requirement is the need to handle multiple serialization formats for the same data model.
The modspec gem provides a LutaML model for the OGC Modular Specification (ModSpec) requirements model, and supports XML and YAML serialization outputs (the “Native ModSpec XML/YAML format”).
The mn-requirements gem needs to provide a Metanorma Requirements XML serialization format for the identical ModSpec model (the “Metanorma Requirements XML format”).
In encoding Metanorma Requirements in ModSpec, the user supplies Native ModSpec YAML which is meant to be transformed into Metanorma Requirements XML.
The transformation process is:
ModSpec YAML ⇒ ModSpec LutaML model
ModSpec LutaML model ⇒ Metanorma Requirements LutaML model
Metanorma Requirements LutaML model ⇒ Metanorma Requirements XML (the “Native Metanorma Requirements XML format”)
In reverse, when the user wants to extract ModSpec YAML from Metanorma Requirements XML:
Metanorma Requirements XML ⇒ Metanorma Requirements LutaML model
Metanorma Requirements LutaML model ⇒ ModSpec LutaML model
ModSpec LutaML model ⇒ ModSpec YAML
A common use case involves transforming between different versions of the same model as it evolves over time.
The Relaton LutaML model demonstrates this pattern:
Model version information is stored in the schema-version attribute of serialized formats of Relaton.
When an older version of the Relaton serialization is parsed, it is first interpreted by the appropriate version of the Relaton serialization LutaML model, and then transformed into the latest version of the Relaton data model.
A version-to-version transform handles model changes
Relaton XML/YAML version attributes:
For transformations across multiple versions, transformations must be applied sequentially in historical order (e.g., “1.0.1” → “1.0.2” → “1.0.3”).
There are several common model transformation patterns:
Generic-to-specific transformation
Specific-to-generic transformation
Many-to-many transformation
When transforming between models, it is common to re-map attributes between different models without changing value types.
Converting a “title” attribute in a “Publication” model to a “name” attribute in a “CatalogEntry” model.
Transforms a general model into a more specific one.
Converting a general “car” model into a specialized “taxi” model.
Transforms a specific model into a more general one.
Converting a specialized “taxi” model into a general “car” model.
Transforms a model that can be represented in multiple ways.
An amphibious vehicle model that can transform into both “car” and “boat” models.
Transforms can be configured to operate in one or both directions.
The reversibility of a transform depends on two things:
whether any mapping rules are one-way transforms
whether the reverse_transform do block is defined
When a transform is defined with only a transform do block that contains bidirectional mapping rules, the transform is bidirectional.
When a transform is defined with only a transform do block that contains unidirectional mapping rules, the transform is unidirectional.
When a transform is defined with a transform do block that contains unidirectional mapping rules, but also a reverse_transform do block that contains reverse unidirectional mapping rules, the transform is bidirectional.
Value transforms operate on individual attribute values, converting from one type or format to another.
A value transform:
Inherits from Lutaml::Value::Transform
Defines source and target value types
Implements the transform method
Implement reverse_transform method if bidirectional
Syntax:
Specifies the source value type. This can be a primitive type or a class that inherits from Lutaml::Value.
Specifies the target value type. This can be a primitive type or a class that inherits from Lutaml::Value.
Defines the transformation logic.
Defines the reverse transformation logic for bidirectional transforms.
Given:
Model transforms operate on entire model structures, mapping attributes between different model representations.
A model transform:
Inherits from Lutaml::Model::Transform
Specifies source and target models
Defines mapping rules within a transform block
Declares directionality
Syntax:
Specifies the source model class.
Specifies the target model class.
Given:
Maps source attributes to target attributes with identical names without value modification.
This type of mapping is bidirectional by default.
Syntax:
The from: and to: parameters are in the LutaML Path syntax.
In LutaML Path syntax, given a source model of { name("John Doe"), email("") }, the path to the name attribute is name, and the path to the email attribute is email.
Maps source attributes to differently named target attributes.
This type of mapping is bidirectional by default.
Syntax:
Maps source attributes to target attributes with value transformation.
The directionality of a transformation mapping depends on the directionality of the value transform.
Syntax:
Nested transforms handle complex object hierarchies, allowing transformation of nested attributes and objects.
A nested transform:
Defines mappings for nested attributes using dot notation
Handles collections appropriately
Supports value transforms within nested mappings
Maps attributes within nested objects.
The directionality of a nested mapping depends on the directionality of the transform.
Syntax:
There are three scenarios in transforming nested attributes:
Value to value transformation
Cross model-value transformation
Model to model transformation
We can apply a value-to-value transformation if both the source and destination attributes are values.
Suppose we have the following source and destination models.
First define a value transform:
Then define a model transform:
The resulting transformation is demonstrated with this diagram.
A cross-model-value transformation occurs when one of the source and destination attributes is a model and the other is a value.
Suppose we have a set of deeper source and destination models.
Here, the UnstructuredDateTimeWithOffset model is a value, and theStructuredDateTimeWithOffset model is a model.
A cross-model-value transform is defined to transform betweenUnstructuredDateTimeWithOffset (value) and StructuredDateTimeWithOffset (model).
Then define a model transform.
The resulting transformation is demonstrated with this diagram.
Model-to-model transformations handle mapping between models.
In a model-to-model transformation, a Value Transform may be used to transform the value of an attribute.
When approaching model to model transformation, the mapping can be placed at the desired level of transformation.
Creating the mapping at the most basic level, where either the mapping source or destination is an attribute accessible at root.
In the mapping, a time path is a root attribute, referring to the attribute of{source|target}.time.
Creating the mapping at the model-to-model level, where both source and destination are models, . Given a deep model hierarchy, the transformation can be applied at a shallow level (e.g. close to the underlying value) or at a deeper level (e.g. close to the top-level model, very nested).
A path of clock.time refers to an inner model attribute, referring to the attribute of {source|target}.clock.time.
A path of computer.clock.time refers to a deeper model attribute, referring to the attribute of {source|target}.computer.clock.time.
The consideration on where the mapping is placed depends on the accessibility, appropriateness and authority of the desired transformation.
A basic level value-to-value or cross-model-value transformation may not be practical when the source and destination models are not managed or owned by the party performing the transformation.
To illustrate such a scenario, we add one more model layer to the same model as in
Now define a model transform between ComputerClock and WallClock.
Notice that different from the
The resulting transformation is demonstrated with this diagram.
Collection transforms handle mapping between collections of objects.
The map_each command is used to specify that the source attribute is a collection.
Syntax:
Collection transforms can also split a single model into multiple entries in a collection. For instance, consider a transform that takes a publication’s authors and converts them into a collection of contributors.
The target_model …, collection: true syntax is used to specify that the target attribute is a collection.
Syntax:
Collection transforms can also join a collection of objects into a single attribute in the target model.
Syntax:
This tutorial demonstrates a complete transformation scenario using a museum’s art collection as an example.
Consider the following model trees.
The “De Lutam’l Art Museum” has a collection of ceramic pieces managed in a register used for generic art information.
The register has the following fields:
This is an example of a YAML file that represents the first model tree:
The museum wants to transform the generic art information model into a ceramic art information model to better manage the ceramic pieces.
We need to create a Lutaml::Model::Transform class that will transform the first model tree into the second model tree.
Let’s first map the fields and group them according to the level of processing
needed. The “source” refes to the GenericArtInformation model, and the “target” refers to the CeramicArtInformation model.
| Source attribute(s) | Target attribute(s) | Value processing needed |
|---|---|---|
| title | title | None |
| description | description | None |
| Source attribute(s) | Target attribute(s) | Value processing needed |
|---|---|---|
| place_of_work | location | None |
| Source attribute(s) | Target attribute(s) | Value processing needed |
| creation_date | creation_date | Convert string to date with time |
| Source attribute(s) | Target attribute(s) | Value processing needed |
| fire_temperature | fire_temperature | Extract from description |
| fire_technique | fire_technique | Extract from description |
| clay_type | clay_type | Extract from description |
| glaze | glaze | Extract from description |
| dimensions | dimensions | Extract specific values and map to Dimensions attributes |
| Source attribute(s) | Target attribute(s) | Value processing needed |
| artist.name | artist.name | None |
| artist.bio | artist.bio | None |
| artist.website | artist.website | None |
| Source attribute(s) | Target attribute(s) | Value processing needed |
| artist.year_born | artist.year_of_birth | None |
| artist.year_died | artist.year_of_death | None |
| Source attribute(s) | Target attribute(s) | Value processing needed |
| artist.bio | artist.techniques | Extract from artist bio |
| artist.bio | artist.awards | Extract from artist bio |
The following Lutaml::Model::Transform class will transform the first model tree into the second model tree. We build this class incrementally by adding the necessary mappings.
Let’s start with mapping the attributes that do not require any processing.
Next, we add the mapping for the attributes that require renaming.
Now let’s add the mapping for the nested attributes.
Next, we add the mapping for the attributes that require value type conversion.
There are two ways we can specify a value transform.
By using a Lutaml::Value::Transform class that implements the transform and reverse_transform methods.
By using a block that takes the source value as an argument and returns the transformed value.
In the first manner, we define the DateFormatTransform class that converts a string to a date with time.
Then the mapping is added to the CeramicArtInformationTransform class like the following.
In the second manner, we can use a block to specify the transformation.
The example follows that we follow the first manner.
Next, we add the mapping for the attributes that require processing.
Now we have to create a transformation for the Dimensions attribute.
Then we add the mapping to the CeramicArtInformationTransform class.
Finally, we add the reverse transformation to the CeramicArtInformationTransform class.
The transformation is now complete.
We can now use the CeramicArtInformationTransform class to transform the data from the first model tree to the second model tree.
The transformed data looks like this.
There are no normative references in this document.