LionWeb-io · ftomassetti · Nov 14, 2025 · Nov 13, 2025 · Nov 13, 2025
diff --git a/website/docs/Guides-Java/comparison.md b/website/docs/Guides-Java/comparison.md
@@ -0,0 +1,90 @@
+---
+title: Nodes Comparison
+sidebar_position: 46
+---
+
+# Nodes Comparison
+
+The lionweb-java project provides comprehensive model comparison capabilities through the `io.lionweb.utils.ModelComparator` class.
+
+The `ModelComparator` enables detailed comparison of models, nodes, and classifier instances to identify structural and semantic differences between them.
+
+## Comparison Methods
+
+The `ModelComparator` provides several overloaded `compare()` methods for different types of elements:
+
+- **Node Comparison**: Compare two `Node` objects
+- **AnnotationInstance Comparison**: Compare two `AnnotationInstance` objects
+- **ClassifierInstance Comparison**: Compare two `ClassifierInstance` objects (polymorphic)
+
+## Static Equivalence Checking
+
+Convenience methods for quick equivalence checks:
+
+- `areEquivalent(ClassifierInstance<?> a, ClassifierInstance<?> b)`: Check if two classifier instances are equivalent
+- `areEquivalent(List<A> as, List<B> bs)`: Check if two lists of classifier instances are equivalent
+
+## ComparisonResult
+
+The `ComparisonResult` class encapsulates the outcome of a comparison operation:
+
+### Key Features
+
+- **Difference Tracking**: Maintains a list of all detected differences
+- **Equivalence Check**: Provides `areEquivalent()` method that returns `true` when no differences exist
+- **Detailed Reporting**: Contains methods to mark specific types of differences
+
+### Types of Differences Detected
+
+1. **ID Differences**: Different node IDs
+2. **Concept Differences**: Different concept/classifier assignments
+3. **Property Value Differences**: Different values for properties
+4. **Containment Differences**: Different numbers or values of child nodes
+5. **Reference Differences**: Different reference targets or resolve information
+6. **Annotation Differences**: Different numbers or values of annotations
+7. **Incompatibility**: When instances cannot be compared (different types)
+
+## Comparison Aspects
+
+The `ModelComparator` performs deep comparison across multiple dimensions:
+
+### 1. **Properties**
+Compares all property values defined by the classifier, identifying any discrepancies in property data.
+
+### 2. **References**
+Compares reference values including:
+- Number of references
+- Referenced node IDs
+- Resolve information for each reference
+
+### 3. **Containments**
+Compares child nodes including:
+- Number of children in each containment
+- Recursive comparison of child node structures
+
+### 4. **Annotations**
+Compares annotations including:
+- Number of annotations
+- Annotation IDs and structures
+
+### 5. **Structure**
+Validates structural consistency including:
+- Parent-child relationships
+- Concept/classifier assignments
+- Node hierarchy
+
+## Use Cases
+
+- **Testing**: Verify that model transformations produce expected results
+- **Validation**: Ensure model consistency across operations
+- **Debugging**: Identify unexpected changes in models
+- **Serialization/Deserialization**: Verify round-trip integrity
+- **Version Control**: Compare model versions to detect changes
+
+## Context Information
+
+All differences are reported with contextual information including:
+- Location in the model hierarchy
+- Node IDs involved
+- Specific feature or property names
+- Index positions for list elements
diff --git a/website/docs/Guides-Java/getting-started.md b/website/docs/Guides-Java/getting-started.md
@@ -36,6 +36,12 @@ Add the following dependency to your `pom.xml`:
 </dependency>
 ```
 
+Or this to your `build.gradle.kts`:
+
+```
+implementation("io.lionweb.lionweb-java:lionweb-java-2024.1-core:${lionwebVersion}")
+```
+
 ## Usage Schema
 
 The typical usage consists in:

diff --git a/website/docs/Guides-Java/index.md b/website/docs/Guides-Java/index.md
@@ -21,8 +21,8 @@ LionWeb is a specification for model-based software engineering that provides:
 ## Features
 
 - Support for the definition nodes and languages
-- Serialization and deserialization in JSON, Protobuf, and Flatbuffers
-- Client-side implementation of the LionWeb bulk protocol, with support for delta coming soon
+- Serialization and deserialization in JSON and Protobuf
+- Client-side implementation of the LionWeb bulk protocol, with support for delta under development
 - Bidirectional conversion between LionWeb and EMF
 - Support for both 2023.1 and 2024.1 specifications
 

diff --git a/website/docs/Guides-Java/roadmap.md b/website/docs/Guides-Java/roadmap.md
@@ -6,8 +6,9 @@ sidebar_position: 3
 
 The project currently support the core specifications.
 
-We will work on implementing support for the delta protocol, as soon as it will be implemented in the LionWeb Repository.
+We released version 1.1 in the course of 2025, and we are steadily progressing on:
+- Implementing support for the Delta protocol
+- Solve any issue reported
+- Constantly optimize performance
 
-We will then proceed to review the project, performing some general maintenance and release version 1.0.
-
-Despite the version number being below 1.0, the project is mature, well tested, and used in production.
+The project is used in production and actively maintained.
diff --git a/website/docs/Guides-Java/validating.md b/website/docs/Guides-Java/validating.md
@@ -0,0 +1,36 @@
+---
+title: Validation
+sidebar_position: 45
+---
+
+# Validation
+
+The lionweb-java project includes a comprehensive validation framework located in the `io.lionweb.utils` package. Here's an overview of all validation-related features:
+
+## Introduction
+
+### **ValidationResult**
+Represents the outcome of validation operations, containing information about any issues found during validation.
+
+### **Issue**
+Represents individual validation problems or concerns detected during the validation process.
+
+Each issue has an _Issue Severity_. The severity levels are error, warning, and info.
+
+## Specific Validators
+
+### **ChunkValidator**
+Validates `SerializationChunks` of data, ensuring they meet structural and semantic requirements.
+
+### **NodeTreeValidator**
+Validates the structure and integrity of node trees within the model hierarchy.
+
+###  **PartitionChunkValidator**
+Specialized validator for validating `SerializationChunks` supposed to contain a single partition.
+
+### **LanguageValidator**
+Validates language definitions, checking that language structures conform to expected patterns and rules.
+
+## Validation Utilities
+
+Notable mention for **CommonChecks**: it provides a collection of common validation checks that can be reused across different validation scenarios.
diff --git a/website/docs/Introduction/annotations.md b/website/docs/Introduction/annotations.md
@@ -0,0 +1,41 @@
+---
+title: Annotations
+sidebar_position: 34
+---
+
+# Annotations
+
+Annotations provide a generic mechanism for extending languages without modifying them. They are useful for:
+
+- cross-cutting concerns that apply across many languages or many kinds of nodes.
+- extending a language we do not own
+
+An annotation definition can be reused with instances of different languages, even if the original language designer never anticipated that extension. This is a key aspect that provides extensibility.
+
+## Generic and Reusable Extensions
+A common example for using annotation is adding comments. You can define a comment annotation once and apply it to any node of any language. Tools that understand this annotation can use it; tools that don’t need it are free to ignore it. This enables optional, non-intrusive extensions. 
+
+This example shows also how annotations are sort of metadata: they are relevant to some users and can be ignored by others. Let's imagine a node with a comment:
+
+- A process generating documentation for a partition may benefit from the comment.
+- At the same time a process executing the partition may ignore the annotation containing the comment, as it is irrelevant for it
+
+Annotations may also be constrained. For instance, you could define a “synonym” annotation that applies only to nodes that provide a name (i.e., implementing the interface `INamed`, part of _LionCore Builtins_). The annotation system supports this level of restriction.
+
+Of course we may also have annotations restricted to specific concepts. Let's imagine we are using a valuable language provided by someone else. We may want to add an extra field to a a certain concept, however we may not control the language and we may not change freely if other tools we use rely on the language being defined in a certain way. We can still add an annotation that, let's say, can be applied to instances of the concept `Car` and could specify a `Color` field. We may then have an editor that is aware of such annotation and can display the node using the color specified in the annotation.
+
+## How Annotations Relate to Nodes
+Annotations behave much like ordinary nodes:
+- both are classifier instances,
+- both carry structured data.
+
+The difference is in their attachment:
+- regular nodes participate in containment trees,
+- annotations are not children of the nodes they describe,
+- instead, they act as metadata associated with nodes.
+
+This avoids mixing cross-cutting information with the primary structure of the model.
+
+Note also that annotations can be attached to nodes but not to other annotations.
+
+Annotations may contain nodes.
diff --git a/website/docs/Introduction/features.md b/website/docs/Introduction/features.md
@@ -1,30 +1,73 @@
 ---
 title: Features
-sidebar_position: 32
+sidebar_position: 35
 ---
 
-# LionWeb Implementations
+# LionWeb Feature Matrix
+
+This page provides a comprehensive overview of the features available across different LionWeb implementations and integrations. Whether you're looking to serialize models, work with language definitions, or connect to a repository server, this matrix will help you choose the right implementation for your needs.
+
+## Understanding the Symbols
+
+Throughout these tables, you'll see the following symbols:
+- ✅ **Fully Supported** - The feature is implemented and ready to use
+- 🏗️ **Under Construction** - The feature is currently being developed
+- ❓ **Status Unknown** - We need to verify the current status of this feature
+- ➖ **Not Applicable** - This feature doesn't apply to this implementation or integration
+
+## LionWeb Implementations
+
+LionWeb implementations are available in five programming languages, each providing core functionality for working with LionWeb models and languages. These libraries form the foundation for building language workbenches, model transformations, and other language engineering tools.
+
+The table below shows which features are available in each language implementation:
 
 | **Feature**                                         | **LW C#** | **LW Java** | **LW Kotlin** | **LW TypeScript** | **LW Python** |
 |-----------------------------------------------------|:---------:|:-----------:|:-------------:|:-----------------:|:-------------:|
 | M1 (model) de/serializer from/to LW JSON            |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | M2 (language) de/serializer from/to LW JSON         |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
+| M1 (model) de/serializer from/to LW Protobuf        |     ➖     |      ✅      |       ✅       |         ✅         |       ✅       |
+| M2 (language) de/serializer from/to LW Protobuf     |     ➖     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Language agnostic (Reflective) API to CRUD LW nodes |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Language specific API to CRUD LW nodes              |     ✅     |      ✅      |       ✅       |         ✅         |       ✅       |
 | Bulk protocol Client                                |     ❓     |      ✅      |       ✅       |         ✅         |       ✅       |
-| Delta protocol Client                               |     ➖     |      🏗️      |       ➖       |         ➖         |       ➖       |
-
-
-# LionWeb Integrations
-
-| **Feature**                  | **MPS** | **EMF** |   **Freon**   | **Rascal** | **Modelix** | **LW Repository** |
-|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|
-| Depends on LW implementation | LW Java | LW Java | LW TypeScript |   LW Java  |      ❓      |   LW TypeScript   |
-| Export to LW M1 (model)      |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |
-| Export to LW M2 (language)   |    ✅    |    ✅    |       ✅       |      ❓     |      ❓      |         ➖         |
-| Import from LW M1 (model)    |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |
-| Import from LW M2 (language) |    ❓    |    ✅    |       ✅       |      ✅     |      ❓      |         ➖         |
-| Bulk protocol Server         |    ❓    |    ➖    |       ➖       |      ➖     |      ✅      |         ✅         |
-| Bulk protocol Client         |    ➖    |    ➖    |       ❓       |      ➖     |      ➖      |         ➖         |
-| Delta protocol Server        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         🏗️         |
-| Delta protocol Client        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         ➖         |
+| Delta protocol Client                               |     🏗     |      🏗️      |       ➖       |         🏗         |       ➖       |
+
+### Key Features Explained
+
+**M1 and M2 Serialization**: All implementations support both model (M1) and language (M2) serialization to and from LionWeb JSON format and [Protobuf](https://protobuf.dev/) format, enabling seamless data exchange between different tools and platforms.
+
+**API Approaches**: Each implementation offers two complementary APIs:
+- **Reflective API**: Work with any LionWeb model dynamically without generated code
+- **Language-specific API**: Use strongly-typed, generated code for compile-time safety and better IDE support
+
+**Protocol Support**: The Bulk protocol allows efficient retrieval and storage of large model partitions. The Delta protocol, currently under development for C#, Typescript, and Java, will enable incremental synchronization of model changes.
+
+## LionWeb Integrations
+
+| **Feature**                  | **MPS** | **EMF** |   **Freon**   | **Rascal** | **Modelix** | **LW Repository** | **Starlasu** |
+|------------------------------|:-------:|:-------:|:-------------:|:----------:|:-----------:|:-----------------:|:------------:|
+| Depends on LW implementation | LW Java | LW Java | LW TypeScript |   LW Java  |      ❓      |   LW TypeScript   | LW Java      |
+| Export to LW M1 (model)      |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |   ✅    |
+| Export to LW M2 (language)   |    ✅    |    ✅    |       ✅       |      ❓     |      ❓      |         ➖         |   ✅    |
+| Import from LW M1 (model)    |    ✅    |    ✅    |       ✅       |      ✅     |      ✅      |         ➖         |   ✅    |
+| Import from LW M2 (language) |    ❓    |    ✅    |       ✅       |      ✅     |      ❓      |         ➖         |   ✅    |
+| Bulk protocol Server         |    ❓    |    ➖    |       ➖       |      ➖     |      ✅      |         ✅         |   ➖    |
+| Bulk protocol Client         |    ➖    |    ➖    |       ❓       |      ➖     |      ➖      |         ➖         |   ➖    |
+| Delta protocol Server        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         🏗️         |   ➖    |
+| Delta protocol Client        |    ➖    |    ➖    |       ➖       |      ➖     |      ➖      |         ➖         |   ➖    |
+
+### Integration Highlights
+
+**MPS and EMF**: The most mature integrations, supporting both model and language import/export. These make it possible to exchange data between JetBrains MPS and Eclipse Modeling Framework projects.
+
+**Freon**: A TypeScript-based language workbench with comprehensive LionWeb support for both models and languages.
+
+**Rascal**: A meta-programming language and toolkit with strong model import/export capabilities.
+
+**Modelix and LW Repository**: These act as server-side repositories, implementing the Bulk protocol to store and serve LionWeb models. The LW Repository is actively developing Delta protocol support for real-time collaborative editing scenarios.
+
+**Starlasu**: This is a family of frameworks for processing textual languages (such as SQL, RPG, COBOL, and many others). More at [Starlasu](https://starlasu.strumenta.com/).
+
+## Contributing
+
+Notice something missing or incorrect? The LionWeb project is community-driven, and we welcome contributions. If you've implemented a feature or know the status of one marked with ❓, please let us know or submit a pull request to update this documentation.
diff --git a/website/docs/Introduction/introduction-to-languages.md b/website/docs/Introduction/introduction-to-languages.md
@@ -1,6 +1,6 @@
 ---
 title: LionWeb Languages
-sidebar_position: 31
+sidebar_position: 32
 ---
 
 ## About LionWeb Languages

diff --git a/website/docs/Introduction/nodes.md b/website/docs/Introduction/nodes.md
@@ -1,6 +1,6 @@
 ---
 title: LionWeb Nodes
-sidebar_position: 30
+sidebar_position: 31
 ---
 
 # Overview of the LionWeb Model

diff --git a/website/docs/Introduction/where-do-my-nodes-live.md b/website/docs/Introduction/where-do-my-nodes-live.md
@@ -0,0 +1,46 @@
+---
+title: Where LionWeb Nodes and Languages Live?
+sidebar_position: 33
+---
+
+# Where LionWeb Nodes and Languages Live?
+
+## In-Memory Only
+Nodes can exist purely in memory. This is typical for short-lived operations:
+- a batch process creates some nodes,
+- performs analysis or transformation,
+- produces an artifact (e.g., a report),
+- discards the nodes when the operation ends.
+
+In this scenario, nodes are regular in-memory objects created through any LionWeb library, without persistence.
+
+## Persistent Repository
+The most common setup is to store nodes in a persistent repository.  
+A repository:
+- keeps nodes and partitions over time,
+- offers services for accessing, querying, and modifying data,
+- acts as the authoritative storage for tools that rely on shared models.
+
+This is the scenario most LionWeb-based systems eventually adopt.
+
+## Files on Disk (JSON or Protobuf)
+Nodes can also be persisted as files:
+- JSON is supported by all LionWeb libraries.
+- Protobuf is supported by most libraries.
+
+You can:
+- store each partition in its own file, or
+- use the archive format (a ZIP container holding multiple encoded partitions).
+
+The archive format is currently available in the Java and Python implementations.  
+It groups multiple partitions and languages into a single compressed file containing protobuf-encoded data.
+
+## Storing Languages
+Languages are nodes too. All storage mechanisms described above apply to languages the same way they apply to regular nodes.
+
+Some considerations:
+- A specialized editor might embed a language definition directly.
+- A language might be shipped as a file alongside the tool.
+- A language may also be constructed programmatically when the editor starts.
+
+These choices depend on how dynamic the language needs to be and how the tool is distributed.