Add new documentation: storage options, validations, annotations, and nodes comparison; adjust sidebar positions

Author: ftomassetti

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

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.

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.

website/docs/Introduction/features.md

@@ -1,6 +1,6 @@
 ---
 title: Features
-sidebar_position: 33
+sidebar_position: 35
 ---
 
 # LionWeb Feature Matrix

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.