Propagate validation errors instead of boolean return value

[Pfeil]

In order to account for simplification, we often use validation on a true/false basis. But I think that sometimes it may be useful to get a list of error messages. As a first step, we should propagate these errors at least in classes such as JsonSchemaValidation. Instead of a boolean, we could return an Optional or so. The boolean style checks can then still performed like boolean isValid = errors.isEmpty() or so. We can then consider in each place this is used how to handle this information. In some parts the boolean logic is likely ok and enough, in others it may make sense to have handling code or provide it to the caller (and possibly to the user, especially when it comes to creating crates).

[Pfeil]

Relevant AI generated ideas/sketches how errors could be propagated and handled without getting in the way with the builder pattern: #264 (comment)

I think the last sketch looks interesting and would be worth looking into.

Backup of the last relevant sketch

[...] A command-based callback system with defined vocabulary will provide much better type safety and predictability. Here's a comprehensive design:

Core Vocabulary & Types

// Validation context input with defined vocabulary
public record ValidationContext(
    EntityType entityType,
    ValidationFailureType failureType,
    String entityId,
    String attemptedValue,
    String expectedFormat,
    Map<String, Object> additionalContext
) {
    public enum EntityType {
        DATA_ENTITY, CONTEXTUAL_ENTITY, ROOT_DATA_ENTITY, JSON_DESCRIPTOR
    }
    
    public enum ValidationFailureType {
        MISSING_CONTEXT_MAPPING,
        INVALID_TYPE_FORMAT,
        UNSUPPORTED_PROPERTY,
        CIRCULAR_REFERENCE,
        DUPLICATE_ID,
        INVALID_ID_FORMAT,
        MISSING_REQUIRED_PROPERTY
    }
}

// Command hierarchy for validation responses
public sealed interface ValidationCommand 
    permits ValidationCommand.Skip, ValidationCommand.Continue, 
            ValidationCommand.Throw, ValidationCommand.DeferThrow,
            ValidationCommand.Substitute, ValidationCommand.LogAndContinue {
    
    record Skip(String reason) implements ValidationCommand {}
    
    record Continue() implements ValidationCommand {}
    
    record Throw(RuntimeException exception) implements ValidationCommand {}
    
    record DeferThrow(RuntimeException exception, DeferralTiming timing) implements ValidationCommand {
        public enum DeferralTiming { AT_BUILD, AT_NEXT_VALIDATION, IMMEDIATE }
    }
    
    record Substitute(AbstractEntity replacementEntity, String reason) implements ValidationCommand {}
    
    record LogAndContinue(LogLevel level, String message) implements ValidationCommand {
        public enum LogLevel { DEBUG, INFO, WARN, ERROR }
    }
}

Callback Interface & Builder Integration

@FunctionalInterface
public interface ValidationCallback {
    ValidationCommand onValidationFailure(ValidationContext context);
    
    // Predefined strategies
    static ValidationCallback strict() {
        return ctx -> new ValidationCommand.Throw(
            new IllegalArgumentException("Validation failed for " + ctx.entityType() + 
                " '" + ctx.entityId() + "': " + ctx.failureType())
        );
    }
    
    static ValidationCallback lenient() {
        return ctx -> new ValidationCommand.Continue();
    }
    
    static ValidationCallback skipInvalid() {
        return ctx -> new ValidationCommand.Skip("Invalid entity skipped: " + ctx.failureType());
    }
    
    static ValidationCallback deferredStrict() {
        return ctx -> new ValidationCommand.DeferThrow(
            new IllegalStateException("Deferred validation failure: " + ctx.failureType()),
            ValidationCommand.DeferThrow.DeferralTiming.AT_BUILD
        );
    }
}

// Enhanced builder with command handling
public class RoCrateBuilder {
    private final ValidationCallback validationCallback;
    private final List<RuntimeException> deferredExceptions = new ArrayList<>();
    
    // Existing constructors + callback versions
    public RoCrateBuilder(ValidationCallback callback) {
        // existing initialization...
        this.validationCallback = callback != null ? callback : ctx -> new ValidationCommand.Continue();
    }
    
    public RoCrateBuilder addDataEntity(DataEntity dataEntity) {
        if (!this.metadataContext.checkEntity(dataEntity)) {
            ValidationContext context = createValidationContext(dataEntity);
            ValidationCommand command = validationCallback.onValidationFailure(context);
            
            switch (command) {
                case ValidationCommand.Skip(String reason) -> {
                    // Log skip reason, don't add entity
                    return this;
                }
                case ValidationCommand.Continue() -> {
                    // Proceed with adding invalid entity
                }
                case ValidationCommand.Throw(RuntimeException ex) -> {
                    throw ex;
                }
                case ValidationCommand.DeferThrow(RuntimeException ex, var timing) -> {
                    deferredExceptions.add(ex);
                    if (timing == ValidationCommand.DeferThrow.DeferralTiming.IMMEDIATE) {
                        throw ex;
                    }
                    // For AT_BUILD, exception thrown in build()
                }
                case ValidationCommand.Substitute(AbstractEntity replacement, String reason) -> {
                    dataEntity = (DataEntity) replacement; // Add the substitute instead
                }
                case ValidationCommand.LogAndContinue(var level, String message) -> {
                    // Log according to level, then continue
                }
            }
        }
        
        this.payload.addDataEntity(dataEntity);
        this.rootDataEntity.addToHasPart(dataEntity.getId());
        return this;
    }
    
    public RoCrate build() {
        // Handle deferred exceptions
        if (!deferredExceptions.isEmpty()) {
            RuntimeException combined = new IllegalStateException(
                "Validation failures during crate construction: " + 
                deferredExceptions.stream().map(Throwable::getMessage).collect(Collectors.joining("; "))
            );
            deferredExceptions.forEach(combined::addSuppressed);
            throw combined;
        }
        
        return new RoCrate(this);
    }
    
    private ValidationContext createValidationContext(AbstractEntity entity) {
        // Determine specific failure type based on checkEntity result
        ValidationContext.ValidationFailureType failureType = determineFailureType(entity);
        return new ValidationContext(
            entity instanceof DataEntity ? ValidationContext.EntityType.DATA_ENTITY 
                                        : ValidationContext.EntityType.CONTEXTUAL_ENTITY,
            failureType,
            entity.getId(),
            // Additional context based on specific failure
            null, null, Map.of()
        );
    }
}

Complex Usage Examples

Example 1: Research Data Crate with Mixed Validation Strategies

// Custom callback for research data with different rules per entity type
ValidationCallback researchDataCallback = ctx -> {
    return switch (ctx.entityType()) {
        case DATA_ENTITY -> switch (ctx.failureType()) {
            case MISSING_CONTEXT_MAPPING -> new ValidationCommand.Substitute(
                createFallbackDataEntity(ctx.entityId()), 
                "Using generic File type for unmapped data entity"
            );
            case INVALID_ID_FORMAT -> new ValidationCommand.Skip(
                "Skipping data entity with malformed ID"
            );
            default -> new ValidationCommand.Continue();
        };
        
        case CONTEXTUAL_ENTITY -> switch (ctx.failureType()) {
            case MISSING_CONTEXT_MAPPING -> new ValidationCommand.LogAndContinue(
                ValidationCommand.LogAndContinue.LogLevel.WARN,
                "Missing context for " + ctx.entityId() + " - may affect interoperability"
            );
            case DUPLICATE_ID -> new ValidationCommand.DeferThrow(
                new IllegalStateException("Duplicate contextual entity: " + ctx.entityId()),
                ValidationCommand.DeferThrow.DeferralTiming.AT_BUILD
            );
            default -> new ValidationCommand.Throw(
                new IllegalArgumentException("Critical contextual entity error: " + ctx.failureType())
            );
        };
        
        default -> new ValidationCommand.Continue();
    };
};

// Build research crate
RoCrate researchCrate = new RoCrateBuilder(
    "Research Dataset XYZ", 
    "Multi-format research data with metadata", 
    "2024-01-15",
    "CC-BY-4.0",
    researchDataCallback
)
.addDataEntity(csvDataFile)           // Might be substituted if unmapped
.addDataEntity(proprietaryDataFile)   // Might be skipped if malformed ID
.addContextualEntity(researcher)      // Might throw on critical errors
.addContextualEntity(organization)    // Might log warnings
.build();                            // Throws if deferred exceptions exist

Example 2: Publishing Workflow with Strict Pre-checks

// Publishing requires all entities to be valid
ValidationCallback publishingCallback = ctx -> {
    // Collect detailed error information for reporting
    String detailedError = String.format(
        "Entity %s (%s) failed validation: %s. Expected: %s, Got: %s",
        ctx.entityId(), ctx.entityType(), ctx.failureType(), 
        ctx.expectedFormat(), ctx.attemptedValue()
    );
    
    return new ValidationCommand.DeferThrow(
        new PublishingValidationException(detailedError, ctx),
        ValidationCommand.DeferThrow.DeferralTiming.AT_BUILD
    );
};

try {
    RoCrate publishableCrate = new RoCrateBuilder(publishingCallback)
        .addDataEntity(dataset)
        .addContextualEntity(author)
        // ... more entities
        .build(); // Will throw PublishingValidationException with all errors
        
    publisher.publish(publishableCrate);
} catch (PublishingValidationException e) {
    // Handle all validation errors at once
    e.getValidationContexts().forEach(ctx -> 
        logger.error("Validation failure: {}", ctx));
}

Example 3: Interactive Crate Builder with User Prompts

// Interactive callback that prompts user for decisions
ValidationCallback interactiveCallback = ctx -> {
    String message = String.format(
        "Validation failed for %s '%s': %s\nChoose action:",
        ctx.entityType(), ctx.entityId(), ctx.failureType()
    );
    
    UserChoice choice = userInterface.promptChoice(message, 
        "Skip", "Continue Anyway", "Fix Manually", "Abort");
        
    return switch (choice) {
        case SKIP -> new ValidationCommand.Skip("User chose to skip");
        case CONTINUE -> new ValidationCommand.Continue();
        case FIX -> {
            AbstractEntity fixed = userInterface.promptEntityFix(ctx);
            yield new ValidationCommand.Substitute(fixed, "User provided fix");
        }
        case ABORT -> new ValidationCommand.Throw(
            new UserAbortedException("User aborted due to validation error")
        );
    };
};

This design provides type safety, predictable behavior, and flexible error handling strategies while maintaining the builder pattern's fluency. The command-based approach allows for sophisticated validation workflows that can adapt to different use cases.