feat(api): introduce DocumentRequest and ProcessedDocumentResponse sealed base classes

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

@@ -46,7 +46,7 @@ default ConvertDocumentResponse convertFiles(Path... files) {
    * If the request is null, default conversion options are applied.
    *
    * @param request an optional {@link ConvertDocumentRequest} specifying conversion settings and parameters
-   * @param files an array of {@link Path} objects representing the file paths to be converted
+   * @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.
@@ -148,8 +148,7 @@ default CompletionStage<ConvertDocumentResponse> convertFilesAsync(@Nullable Con
   private ConvertDocumentRequest createRequest(@Nullable ConvertDocumentRequest request, Path... files) {
     ValidationUtils.ensureNotEmpty(files, "files");
 
-    var builder = Optional.ofNullable(request)
-        .map(ConvertDocumentRequest::toBuilder)
+    var builder = Optional.ofNullable(request).<ConvertDocumentRequest.Builder<?, ?>>map(ConvertDocumentRequest::toBuilder)
         .orElseGet(ConvertDocumentRequest::builder);
 
     FileUtils.createFileSources(files)

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/chunk/request/ChunkDocumentRequest.java

@@ -1,35 +1,18 @@
 package ai.docling.serve.api.chunk.request;
 
-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;
 
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
-import ai.docling.serve.api.convert.request.source.Source;
-import ai.docling.serve.api.convert.request.target.Target;
+import ai.docling.serve.api.request.DocumentRequest;
 
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
 @tools.jackson.databind.annotation.JsonDeserialize(builder = ChunkDocumentRequest.ChunkDocumentRequestBuilder.class)
 @lombok.experimental.SuperBuilder(toBuilder = true)
 @lombok.Getter
-@lombok.ToString
-public sealed abstract class ChunkDocumentRequest permits HierarchicalChunkDocumentRequest, HybridChunkDocumentRequest {
-  /**
-   * List of input document sources to process.
-   *
-   * @param sources the list of document sources
-   * @return the list of document sources
-   */
-  @JsonProperty("sources")
-  @JsonSetter(nulls = Nulls.AS_EMPTY)
-  @lombok.Singular
-  private List<Source> sources;
-
+@lombok.ToString(callSuper = true)
+public sealed abstract class ChunkDocumentRequest extends DocumentRequest
+    permits HierarchicalChunkDocumentRequest, HybridChunkDocumentRequest {
   /**
    * Conversion options.
    *
@@ -41,16 +24,6 @@ public sealed abstract class ChunkDocumentRequest permits HierarchicalChunkDocum
   @lombok.Builder.Default
   private ConvertDocumentOptions options = ConvertDocumentOptions.builder().build();
 
-  /**
-   * Specification for the type of output target.
-   *
-   * @param target the output target specification, or null if not specified
-   * @return the output target specification, or null if not specified
-   */
-  @JsonProperty("target")
-  @Nullable
-  private Target target;
-
   /**
    * If true, the output will include both the chunks and the converted document.
    *
@@ -61,7 +34,6 @@ public sealed abstract class ChunkDocumentRequest permits HierarchicalChunkDocum
   private boolean includeConvertedDoc;
 
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
-  public static abstract class ChunkDocumentRequestBuilder<C extends ChunkDocumentRequest, B extends ChunkDocumentRequestBuilder<C, B>> {
-    // Lombok's @SuperBuilder generates the actual implementation
+  public abstract static class ChunkDocumentRequestBuilder<C extends ChunkDocumentRequest, B extends ChunkDocumentRequestBuilder<C, B>> extends DocumentRequest.DocumentRequestBuilder<C, B> {
   }
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/chunk/response/ChunkDocumentResponse.java

@@ -7,19 +7,23 @@
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.annotation.Nulls;
 
+import ai.docling.serve.api.response.ProcessedDocumentResponse;
+
 /**
  * Response returned by the Chunk API for a single conversion request.
  *
  * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
  * collections/strings are omitted from JSON output.</p>
+ *
+ * @see ProcessedDocumentResponse
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
 @tools.jackson.databind.annotation.JsonDeserialize(builder = ChunkDocumentResponse.Builder.class)
 @lombok.extern.jackson.Jacksonized
 @lombok.Builder(toBuilder = true)
 @lombok.Getter
 @lombok.ToString
-public class ChunkDocumentResponse {
+public final class ChunkDocumentResponse extends ProcessedDocumentResponse {
 
   /**
    * List of document chunks.
@@ -55,17 +59,18 @@ public class ChunkDocumentResponse {
   /**
    * Builder for creating {@link ChunkDocumentResponse} instances.
    * Generated by Lombok's {@code @Builder} annotation.
-   * 
+   *
    * <p>Builder methods:
    * <ul>
-   *   <li>{@code chunk(Chunk)} - Add a single chunk (use with @Singular)</li>
-   *   <li>{@code chunks(List<Chunk>)} - Set the list of chunks</li>
-   *   <li>{@code document(Document)} - Add a single document (use with @Singular)</li>
-   *   <li>{@code documents(List<Document>)} - Set the list of converted documents</li>
-   *   <li>{@code processingTime(Double)} - Set the processing time in seconds</li>
+   * <li>{@code chunk(Chunk)} - Add a single chunk (use with @Singular)</li>
+   * <li>{@code chunks(List<Chunk>)} - Set the list of chunks</li>
+   * <li>{@code document(Document)} - Add a single document (use with @Singular)</li>
+   * <li>{@code documents(List<Document>)} - Set the list of converted documents</li>
+   * <li>{@code processingTime(Double)} - Set the processing time in seconds</li>
    * </ul>
    */
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
-  public static class Builder { }
+  public static class Builder {
+  }
 
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/BatchConvertDocumentRequest.java

@@ -1,56 +1,38 @@
 package ai.docling.serve.api.convert.request;
 
 import java.util.List;
+import java.util.Objects;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 import com.fasterxml.jackson.annotation.JsonSetter;
 import com.fasterxml.jackson.annotation.Nulls;
 
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
-import ai.docling.serve.api.convert.request.source.Source;
 import ai.docling.serve.api.convert.request.target.Target;
+import ai.docling.serve.api.request.DocumentRequest;
 
 /**
  * Represents a request to batch convert document sources. The batch endpoint processes multiple
  * documents asynchronously and returns a task ID for tracking progress. Sources can be HTTP URLs
  * or S3 buckets, and results are delivered to a presigned URL or S3 target.
  *
+ * <p>Unlike {@link ConvertDocumentRequest}, the {@linkplain #getTarget() target} is required
+ * for batch requests — it must be either a
+ * {@link ai.docling.serve.api.convert.request.target.PresignedUrlTarget} or
+ * {@link ai.docling.serve.api.convert.request.target.S3Target}.
+ *
  * <p>This class is serialized into JSON to conform to the API specification using
  * {@link JsonProperty} annotations. Fields with {@code null} values or empty collections
  * are omitted from the serialized JSON using {@link JsonInclude}.
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
-@tools.jackson.databind.annotation.JsonDeserialize(builder = BatchConvertDocumentRequest.Builder.class)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = BatchConvertDocumentRequest.BuilderImpl.class)
 @lombok.extern.jackson.Jacksonized
-@lombok.Builder(toBuilder = true)
+@lombok.experimental.SuperBuilder(toBuilder = true)
 @lombok.Getter
-@lombok.ToString
-public class BatchConvertDocumentRequest {
-  /**
-   * List of document sources to be converted.
-   * Each source can be an HTTP URL or S3 reference.
-   *
-   * @param sources the list of document sources
-   * @return the list of document sources
-   */
-  @JsonProperty("sources")
-  @JsonSetter(nulls = Nulls.AS_EMPTY)
-  @lombok.Singular
-  private List<Source> sources;
-
-  /**
-   * Target specification for where the converted documents should be delivered.
-   * Must be either a {@link ai.docling.serve.api.convert.request.target.PresignedUrlTarget}
-   * or {@link ai.docling.serve.api.convert.request.target.S3Target}.
-   *
-   * @param target the output target
-   * @return the output target
-   */
-  @JsonProperty("target")
-  @lombok.NonNull
-  private Target target;
-
+@lombok.ToString(callSuper = true)
+public final class BatchConvertDocumentRequest extends DocumentRequest {
   /**
    * Options controlling the document conversion process.
    * Includes settings for OCR, output formats, processing pipelines, and more.
@@ -75,19 +57,16 @@ public class BatchConvertDocumentRequest {
   private List<CallbackSpec> callbacks;
 
   /**
-   * Builder for creating {@link BatchConvertDocumentRequest} instances.
-   * Generated by Lombok's {@code @Builder} annotation.
+   * Returns the output target, which is required for batch requests.
    *
-   * <p>Builder methods:
-   * <ul>
-   *   <li>{@code source(Source)} - Add a single document source</li>
-   *   <li>{@code sources(List<Source>)} - Set the list of document sources</li>
-   *   <li>{@code target(Target)} - Set the output target</li>
-   *   <li>{@code options(ConvertDocumentOptions)} - Set the conversion options</li>
-   *   <li>{@code callback(CallbackSpec)} - Add a single callback specification</li>
-   *   <li>{@code callbacks(List<CallbackSpec>)} - Set the list of callback specifications</li>
-   * </ul>
+   * @return the output target, never null
    */
+  @Override
+  public Target getTarget() {
+    return Objects.requireNonNull(super.getTarget(), "target is marked non-null but is null");
+  }
+
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
-  public static class Builder { }
+  public abstract static class BatchConvertDocumentRequestBuilder<C extends BatchConvertDocumentRequest, B extends BatchConvertDocumentRequestBuilder<C, B>> extends DocumentRequest.DocumentRequestBuilder<C, B> {
+  }
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/request/ConvertDocumentRequest.java

@@ -1,17 +1,10 @@
 package ai.docling.serve.api.convert.request;
 
-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;
 
 import ai.docling.serve.api.convert.request.options.ConvertDocumentOptions;
-import ai.docling.serve.api.convert.request.source.Source;
-import ai.docling.serve.api.convert.request.target.Target;
+import ai.docling.serve.api.request.DocumentRequest;
 
 /**
  * Represents a request to convert a document. The request includes the source(s) of the document,
@@ -22,24 +15,12 @@
  * are omitted from the serialized JSON using {@link JsonInclude}.
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
-@tools.jackson.databind.annotation.JsonDeserialize(builder = ConvertDocumentRequest.Builder.class)
+@tools.jackson.databind.annotation.JsonDeserialize(builder = ConvertDocumentRequest.BuilderImpl.class)
 @lombok.extern.jackson.Jacksonized
-@lombok.Builder(toBuilder = true)
+@lombok.experimental.SuperBuilder(toBuilder = true)
 @lombok.Getter
-@lombok.ToString
-public class ConvertDocumentRequest {
-  /**
-   * List of document sources to be converted.
-   * Each source can be a file (base64-encoded) or an HTTP URL.
-   *
-   * @param sources the list of document sources
-   * @return the list of document sources
-   */
-  @JsonProperty("sources")
-  @JsonSetter(nulls = Nulls.AS_EMPTY)
-  @lombok.Singular
-  private List<Source> sources;
-
+@lombok.ToString(callSuper = true)
+public final class ConvertDocumentRequest extends DocumentRequest {
   /**
    * Options controlling the document conversion process.
    * Includes settings for OCR, output formats, processing pipelines, and more.
@@ -52,29 +33,7 @@ public class ConvertDocumentRequest {
   @lombok.Builder.Default
   private ConvertDocumentOptions options = ConvertDocumentOptions.builder().build();
 
-  /**
-   * Target specification for where the converted document should be delivered.
-   * If not specified, the result is returned in the response body.
-   *
-   * @param target the output target, or null if not specified
-   * @return the output target, or null if not specified
-   */
-  @JsonProperty("target")
-  @Nullable
-  private Target target;
-
-  /**
-   * Builder for creating {@link ConvertDocumentRequest} instances.
-   * Generated by Lombok's {@code @Builder} annotation.
-   * 
-   * <p>Builder methods:
-   * <ul>
-   *   <li>{@code source(Source)} - Add a single document source (use with @Singular)</li>
-   *   <li>{@code sources(List<Source>)} - Set the list of document sources</li>
-   *   <li>{@code options(ConvertDocumentOptions)} - Set the conversion options</li>
-   *   <li>{@code target(Target)} - Set the output target</li>
-   * </ul>
-   */
   @tools.jackson.databind.annotation.JsonPOJOBuilder(withPrefix = "")
-  public static class Builder { }
+  public abstract static class ConvertDocumentRequestBuilder<C extends ConvertDocumentRequest, B extends ConvertDocumentRequestBuilder<C, B>> extends DocumentRequest.DocumentRequestBuilder<C, B> {
+  }
 }

docling-serve/docling-serve-api/src/main/java/ai/docling/serve/api/convert/response/ConvertDocumentResponse.java

@@ -1,8 +1,9 @@
 package ai.docling.serve.api.convert.response;
 
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
 
+import ai.docling.serve.api.response.ProcessedDocumentResponse;
 import ai.docling.serve.api.serialization.Jackson2ConvertDocumentResponseDeserializer;
 import ai.docling.serve.api.serialization.Jackson3ConvertDocumentResponseDeserializer;
 
@@ -14,12 +15,14 @@
  *
  * <p>Serialization uses {@link JsonInclude.Include#NON_EMPTY}, so nulls and empty
  * collections/strings are omitted from JSON output.</p>
+ *
+ * @see ProcessedDocumentResponse
  */
 @JsonInclude(JsonInclude.Include.NON_EMPTY)
 @com.fasterxml.jackson.databind.annotation.JsonDeserialize(using = Jackson2ConvertDocumentResponseDeserializer.class)
 @tools.jackson.databind.annotation.JsonDeserialize(using = Jackson3ConvertDocumentResponseDeserializer.class)
-public abstract sealed class ConvertDocumentResponse permits InBodyConvertDocumentResponse, PreSignedUrlConvertDocumentResponse,
-    PreSignedUrlConvertResponse, ZipArchiveConvertDocumentResponse {
+public abstract sealed class ConvertDocumentResponse extends ProcessedDocumentResponse permits InBodyConvertDocumentResponse,
+    PreSignedUrlConvertDocumentResponse, PreSignedUrlConvertResponse, ZipArchiveConvertDocumentResponse {
   /**
    * Type of response
    *