Update Error codes docs

Author: Yauhenikapl

core/esmf-aspect-model-validator/src/main/java/org/eclipse/esmf/aspectmodel/validation/services/ViolationFormatter.java

@@ -42,6 +42,9 @@ public class ViolationFormatter implements Function<List<Violation>, String>, Vi
    protected final String additionalHints;
    protected final RustLikeFormatter formatter;
 
+   private static final String ERROR_CODES_DOC_LINK = "https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/error-codes.html";
+   private static final String ERROR_CODES_DOC_STRING = "For more information, see: documentation: " + ERROR_CODES_DOC_LINK;
+
    public ViolationFormatter( final String additionalHints ) {
       this( new PlainTextFormatter(), additionalHints );
    }
@@ -93,7 +96,7 @@ public String apply( final List<Violation> violations ) {
                      .append( possibleFix.description() );
             }
             // Add documentation link
-            builder.append( String.format( "  > For more information, see: https://eclipse-esmf.github.io/esmf-sdk/tooling-guide/error-codes.html#%s%n", 
+            builder.append( String.format( ERROR_CODES_DOC_STRING + "#%s%n",
                   errorCode.toLowerCase().replace( "_", "-" ) ) );
             builder.append( System.lineSeparator() );
          }
@@ -108,15 +111,15 @@ public String apply( final List<Violation> violations ) {
             final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
             builder.append( String.format( "> %s%n", enhancedMessage ) );
             // Add documentation link for context-free violations
-            builder.append( "  > For more information, see: documentation: https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/error-codes.html"
+            builder.append( ERROR_CODES_DOC_STRING
                   + errorCode.toLowerCase().replace( "_", "-" ) );
          } else {
             final String errorCode = violation.errorCode();
             final String enhancedMessage = String.format( "[%s] %s", errorCode, violation.message() );
             builder.append( String.format( "> %s: %n", enhancedMessage ) );
             builder.append( indent( violation.accept( this ), 2 ) ).append( System.lineSeparator() );
             // Add documentation link
-            builder.append( "  > For more information, see: documentation: https://eclipse-esmf.github.io/esmf-developer-guide/tooling-guide/error-codes.html"
+            builder.append( ERROR_CODES_DOC_STRING
                   + errorCode.toLowerCase().replace( "_", "-" ) );
          }
          builder.append( System.lineSeparator() );

documentation/developer-guide/modules/tooling-guide/examples/CustomViolationFormatter.java

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025 Robert Bosch Manufacturing Solutions GmbH
+ *
+ * See the AUTHORS file(s) distributed with this work for additional
+ * information regarding authorship.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ *
+ * SPDX-License-Identifier: MPL-2.0
+ */
+
+package examples;
+
+// tag::imports[]
+import java.util.List;
+import java.util.Map;
+import java.util.stream.Collectors;
+
+import org.eclipse.esmf.aspectmodel.shacl.violation.DatatypeViolation;
+import org.eclipse.esmf.aspectmodel.shacl.violation.MaxCountViolation;
+import org.eclipse.esmf.aspectmodel.shacl.violation.Violation;
+// end::imports[]
+
+public class CustomViolationFormatter implements Violation.Visitor<String> {
+
+   // tag::custom-formatter[]
+   // Implement other visitor methods for different violation types
+   @Override
+   public String visit(Violation violation) {
+      // Generic fallback for unhandled violation types
+      return String.format("Validation error: %s", violation.message());
+   }
+   // end::custom-formatter[]
+
+   // tag::error-aggregation[]
+   public void aggregateErrors(List<Violation> violations) {
+       // Group violations by error code for batch processing
+       Map<String, List<Violation>> errorsByCode = violations.stream()
+           .collect(Collectors.groupingBy(Violation::errorCode));
+
+       // Handle each error type separately
+       List<Violation> dataTypeErrors = errorsByCode.get("ERR_TYPE");
+       List<Violation> cardinalityErrors = errorsByCode.get("ERR_MAX_COUNT");
+       
+       // Process each error type with specific handling logic
+       if (dataTypeErrors != null && !dataTypeErrors.isEmpty()) {
+           System.out.println("Found " + dataTypeErrors.size() + " data type errors");
+           // Handle data type errors...
+       }
+       
+       if (cardinalityErrors != null && !cardinalityErrors.isEmpty()) {
+           System.out.println("Found " + cardinalityErrors.size() + " cardinality errors");
+           // Handle cardinality errors...
+       }
+   }
+   // end::error-aggregation[]
+}

documentation/developer-guide/modules/tooling-guide/nav.adoc

@@ -2,4 +2,5 @@
 * xref:java-aspect-tooling.adoc[Java APIs for Aspect Models]
 * xref:maven-plugin.adoc[Maven Plugin]
 * xref:error-codes.adoc[Error Codes and Validation Results]
+* xref:best-practices.adoc[Best Practices]
 * xref:bamm-migration.adoc[Migration from BAMM]

documentation/developer-guide/modules/tooling-guide/pages/best-practices.adoc

@@ -0,0 +1,27 @@
+:page-partial:
+
+[[best-practices]]
+= Best Practices
+
+This guide provides best practices for developing Aspect Models and handling validation errors effectively.
+
+[[analyzing-modeling-errors]]
+== Analyzing Modeling Errors
+
+When working with ESMF SDK validation results, follow these practices to efficiently identify and resolve modeling issues.
+
+=== Model Development
+
+1. **Validate Early**: Run validation frequently during model development
+2. **Use Detailed Output**: Enable detailed error reporting for comprehensive feedback
+3. **Address Errors Systematically**: Start with meta-violations before fixing constraint violations
+4. **Test Edge Cases**: Verify models with boundary values and optional properties
+
+=== Error Handling
+
+1. **Programmatic Handling**: Use the visitor pattern for type-safe error handling
+2. **User-Friendly Messages**: Transform technical errors into user-friendly guidance
+3. **Logging**: Log error codes and context for troubleshooting
+4. **Documentation**: Link to error code documentation in error messages where appropriate
+
+