feat: Add validation error handling to API and client layers (#241)

- Implemented `ValidationException` and supporting classes to handle `422` validation errors returned by the server.
- Updated all API methods to throw `ValidationException` when applicable.
- Added support for detailed validation error responses, including error context and locations.
- Enhanced test coverage for validation cases in client and hierarchical/hybrid chunking workflows.
- Updated documentation and release notes to reflect validation error handling changes.

Fixes #240

Signed-off-by: Eric Deandrea <[email protected]>

Author: edeandrea

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeChunkApi.java

@@ -21,6 +21,9 @@ public interface DoclingServeChunkApi {
   /**
    * Converts and chunks the provided document source(s) into a processed document based on the specified options
    * and using a hierarchical chunker for splitting the document into smaller chunks.
+   * @param request the request containing the document source(s) and options for hierarchical chunking
+   * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the converted document,
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ChunkDocumentResponse chunkSourceWithHierarchicalChunker(HierarchicalChunkDocumentRequest request);
 
@@ -32,6 +35,7 @@ public interface DoclingServeChunkApi {
    * @param files the files to be processed and chunked using the hierarchical chunker
    * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
    *         converted documents, and associated metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(Path... files) {
     return chunkFilesWithHierarchicalChunker(null, files);
@@ -49,6 +53,7 @@ default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(Path... files) {
    * @param files   the files to be processed and chunked using the hierarchical chunker.
    * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
    *         converted documents, and associated metadata.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(@Nullable HierarchicalChunkDocumentRequest request, Path... files) {
     return chunkSourceWithHierarchicalChunker(createHierarchicalChunkRequest(request, files));
@@ -63,6 +68,7 @@ default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(@Nullable Hierar
    *                chunker configurations, and optional specifications for output targets
    * @return a {@link ChunkDocumentResponse} containing the processed chunks, optionally the
    *         converted document, and other relevant metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ChunkDocumentResponse chunkSourceWithHybridChunker(HybridChunkDocumentRequest request);
 
@@ -74,6 +80,7 @@ default ChunkDocumentResponse chunkFilesWithHierarchicalChunker(@Nullable Hierar
    * @param files the files to be processed and chunked using the hybrid chunker
    * @return a {@link ChunkDocumentResponse} containing the processed chunks,
    *         optionally the converted documents, and associated metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ChunkDocumentResponse chunkFilesWithHybridChunker(Path... files) {
     return chunkFilesWithHybridChunker(null, files);
@@ -91,6 +98,7 @@ default ChunkDocumentResponse chunkFilesWithHybridChunker(Path... files) {
    * @param files   the files to be processed and chunked using the hybrid chunking strategy.
    * @return a {@code ChunkDocumentResponse} containing the processed chunks, optionally the
    *         converted documents, and associated metadata.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ChunkDocumentResponse chunkFilesWithHybridChunker(@Nullable HybridChunkDocumentRequest request, Path... files) {
     return chunkSourceWithHybridChunker(createHybridChunkRequest(request, files));
@@ -104,6 +112,7 @@ default ChunkDocumentResponse chunkFilesWithHybridChunker(@Nullable HybridChunkD
    * @param request the request containing the document source(s) and options for hierarchical chunking
    * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse}, which contains
    *         the processed chunks, optionally the converted document, and processing metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   CompletionStage<ChunkDocumentResponse> chunkSourceWithHierarchicalChunkerAsync(HierarchicalChunkDocumentRequest request);
 
@@ -117,6 +126,7 @@ default ChunkDocumentResponse chunkFilesWithHybridChunker(@Nullable HybridChunkD
    * @return a {@link CompletionStage} resolving to a {@link ChunkDocumentResponse}, which
    *         includes the processed chunks, optionally the converted documents, and associated
    *         metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunkerAsync(Path... files) {
     return chunkFilesWithHierarchicalChunkerAsync(null, files);
@@ -135,6 +145,7 @@ default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunker
    * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse},
    *         which includes the processed chunks, optionally the converted documents,
    *         and associated metadata.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunkerAsync(@Nullable HierarchicalChunkDocumentRequest request, Path... files) {
     return chunkSourceWithHierarchicalChunkerAsync(createHierarchicalChunkRequest(request, files));
@@ -149,6 +160,7 @@ default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunker
    *                hybrid chunking parameters, and optional specifications for output targets
    * @return a {@link CompletionStage} that resolves to a {@link ChunkDocumentResponse}, which includes
    *         the processed chunks, optionally the converted document, and relevant processing metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   CompletionStage<ChunkDocumentResponse> chunkSourceWithHybridChunkerAsync(HybridChunkDocumentRequest request);
 
@@ -159,6 +171,7 @@ default CompletionStage<ChunkDocumentResponse> chunkFilesWithHierarchicalChunker
    *              a valid file location.
    * @return A CompletionStage that, when completed, holds a ChunkDocumentResponse containing
    *         the results of the chunking operation.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ChunkDocumentResponse> chunkFilesWithHybridChunkerAsync(Path... files) {
     return chunkFilesWithHybridChunkerAsync(null, files);
@@ -173,6 +186,7 @@ default CompletionStage<ChunkDocumentResponse> chunkFilesWithHybridChunkerAsync(
    *                Must not be null or empty.
    * @return A {@code CompletionStage<ChunkDocumentResponse>} that completes with the resulting
    *         {@code ChunkDocumentResponse} once the chunking operation is finished.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ChunkDocumentResponse> chunkFilesWithHybridChunkerAsync(@Nullable HybridChunkDocumentRequest request, Path... files) {
     return chunkSourceWithHybridChunkerAsync(createHybridChunkRequest(request, files));

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeClearApi.java

@@ -33,6 +33,7 @@ public interface DoclingServeClearApi {
    *                or other parameters.
    * @return a {@link ClearResponse} object indicating the status of the clear
    *         operation, such as success or failure.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ClearResponse clearResults(ClearResultsRequest request);
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeConvertApi.java

@@ -22,6 +22,7 @@ public interface DoclingServeConvertApi {
    *
    * @param request the {@link ConvertDocumentRequest} containing the source(s), conversion options, and optional target.
    * @return a {@link ConvertDocumentResponse} containing the processed document data, processing details, and any errors.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ConvertDocumentResponse convertSource(ConvertDocumentRequest request);
 
@@ -32,6 +33,7 @@ public interface DoclingServeConvertApi {
    *
    * @param files an array of {@link Path} objects representing the file paths to be converted
    * @return a {@link ConvertDocumentResponse} containing the processed document data, metadata, and any errors
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ConvertDocumentResponse convertFiles(Path... files) {
     return convertFiles(null, files);
@@ -45,6 +47,7 @@ default ConvertDocumentResponse convertFiles(Path... files) {
    * @param files an array of {@link Path} objects representing the file paths to be converted
    * @return a {@link ConvertDocumentResponse} containing the processed document data, any errors encountered,
    *         and additional processing metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default ConvertDocumentResponse convertFiles(@Nullable ConvertDocumentRequest request, Path... files) {
     return convertSource(createRequest(request, files));
@@ -69,6 +72,7 @@ default ConvertDocumentResponse convertFiles(@Nullable ConvertDocumentRequest re
    * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
    *         when the conversion is finished, or completes exceptionally if the conversion fails
    *         or times out.
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   CompletionStage<ConvertDocumentResponse> convertSourceAsync(ConvertDocumentRequest request);
 
@@ -80,6 +84,7 @@ default ConvertDocumentResponse convertFiles(@Nullable ConvertDocumentRequest re
    * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
    *         when the conversion finishes, or completes exceptionally if the conversion fails
    *         or times out
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ConvertDocumentResponse> convertFilesAsync(Path... files) {
     return convertFilesAsync(null, files);
@@ -96,6 +101,7 @@ default CompletionStage<ConvertDocumentResponse> convertFilesAsync(Path... files
    * @return a {@link CompletionStage} that completes with the {@link ConvertDocumentResponse}
    *         when the conversion finishes, or completes exceptionally if the conversion fails
    *         or times out
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   default CompletionStage<ConvertDocumentResponse> convertFilesAsync(@Nullable ConvertDocumentRequest request, Path... files) {
     return convertSourceAsync(createRequest(request, files));

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/DoclingServeTaskApi.java

@@ -27,6 +27,7 @@ public interface DoclingServeTaskApi {
    *                wait time between polling attempts
    * @return a {@link TaskStatusPollResponse} encapsulating the current status, position in the
    *         queue, and optional metadata for the specified task
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   TaskStatusPollResponse pollTaskStatus(TaskStatusPollRequest request);
 
@@ -41,6 +42,7 @@ public interface DoclingServeTaskApi {
    *                for which the result is to be converted
    * @return a {@link ConvertDocumentResponse} encapsulating the converted document,
    *         processing status, timings, and potential errors
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ConvertDocumentResponse convertTaskResult(TaskResultRequest request);
 
@@ -56,6 +58,7 @@ public interface DoclingServeTaskApi {
    *                the task whose result is to be processed and chunked
    * @return a {@link ChunkDocumentResponse} containing the chunked result,
    *         associated documents, processing time, and additional relevant metadata
+   * @throws ai.docling.serve.api.validation.ValidationException If request validation fails for any reason.
    */
   ChunkDocumentResponse chunkTaskResult(TaskResultRequest request);
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/validation/ValidationError.java

@@ -0,0 +1,49 @@
+package ai.docling.serve.api.validation;
+
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonSetter;
+import com.fasterxml.jackson.annotation.Nulls;
+
+/**
+ * Represents a validation error with customizable serialization and deserialization behavior.
+ *
+ * This class includes Jackson annotations for JSON handling and Lombok annotations for
+ * boilerplate code generation, such as getters and builder patterns.
+ *
+ * It is designed to be used in scenarios where structured validation error
+ * details are required to be captured and processed.
+ *
+ * An inner static Builder class is provided for constructing ValidationError instances
+ * using the builder pattern.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = ValidationError.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ValidationError {
+  /**
+   * A collection of validation error details associated with the validation error.
+   *
+   * @param errorDetails the collection of validation error details
+   * @return the collection of validation error details
+   */
+  @JsonProperty("detail")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<ValidationErrorDetail> errorDetails;
+
+  /**
+   * Builder class for constructing instances of the enclosing class.
+   *
+   * This class is used to implement the builder pattern, enabling the creation
+   * of objects with a more readable and flexible initialization format. The builder
+   * follows the fluent API design by allowing method chaining.
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/validation/ValidationErrorContext.java

@@ -0,0 +1,47 @@
+package ai.docling.serve.api.validation;
+
+import org.jspecify.annotations.Nullable;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+
+/**
+ * Represents the context information associated with a validation error.
+ *
+ * This class provides additional details about the validation error,
+ * such as the expected schemes relevant to the validation process.
+ *
+ * The class leverages Jackson annotations for JSON serialization and
+ * deserialization, and Lombok annotations to reduce boilerplate code,
+ * including getter methods and builder patterns.
+ *
+ * The builder pattern is implemented through an inner static `Builder` class
+ * for flexible and readable object construction.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = ValidationErrorContext.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ValidationErrorContext {
+  /**
+   * Specifies the expected schemes relevant to a validation process.
+   *
+   * @param expectedSchemes the expected schemes relevant to a validation process
+   * @return the expected schemes relevant to a validation process
+   */
+  @JsonProperty("expected_schemes")
+  @Nullable
+  private String expectedSchemes;
+
+  /**
+   * Builder class for constructing instances of the enclosing class.
+   *
+   * This class implements the builder pattern, providing a convenient and flexible
+   * approach to construct objects of the enclosing class. It allows for a fluent
+   * API style by enabling method chaining during object creation.
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+}

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/validation/ValidationErrorDetail.java

@@ -0,0 +1,86 @@
+package ai.docling.serve.api.validation;
+
+import java.util.List;
+
+import org.jspecify.annotations.Nullable;
+
+import com.fasterxml.jackson.annotation.JsonInclude;
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.annotation.JsonSetter;
+import com.fasterxml.jackson.annotation.Nulls;
+
+/**
+ * Represents detailed information about a validation error.
+ *
+ * This class provides structured data associated with a validation error,
+ * including the locations of the error, an error message, the type of
+ * validation error, and the input causing the error.
+ */
+@JsonInclude(JsonInclude.Include.NON_EMPTY)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = ValidationErrorDetail.Builder.class)
+@lombok.extern.jackson.Jacksonized
+@lombok.Builder(toBuilder = true)
+@lombok.Getter
+@lombok.ToString
+public class ValidationErrorDetail {
+  /**
+   * Represents the specific locations associated with a validation error.
+   *
+   * @param loc the specific locations associated with a validation error
+   * @return the specific locations associated with a validation error
+   */
+  @JsonProperty("loc")
+  @JsonSetter(nulls = Nulls.AS_EMPTY)
+  @lombok.Singular
+  private List<Object> locations;
+
+  /**
+   * Represents an optional validation error message.
+   *
+   * @param message the optional validation error message
+   * @return the optional validation error message
+   */
+  @JsonProperty("msg")
+  @Nullable
+  private String message;
+
+  /**
+   * Represents the type of validation error.
+   *
+   * @param type the type of validation error
+   * @return the type of validation error
+   */
+  @JsonProperty("type")
+  @Nullable
+  private String type;
+
+  /**
+   * Represents the input causing the validation error.
+   *
+   * @param input the input causing the validation error
+   * @return the input causing the validation error
+   */
+  @JsonProperty("input")
+  @Nullable
+  private String input;
+
+  /**
+   * Represents the context information associated with a validation error.
+   *
+   * @param context the context information associated with a validation error
+   * @return the context information associated with a validation error
+   */
+  @JsonProperty("ctx")
+  @lombok.NonNull
+  @lombok.Builder.Default
+  private ValidationErrorContext context = ValidationErrorContext.builder().build();
+
+  /**
+   * Builder class for constructing instances of the enclosing class.
+   *
+   * This class is used to implement the builder pattern, providing a flexible
+   * and readable mechanism for initializing instances of the enclosing class.
+   */
+  @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
+  public static class Builder { }
+}