Initial architecture & purpose

[edeandrea]

Thanks @dolfim-ibm for getting this set up! I wanted to put forward some ideas on how we should move forward with this repo. Before that, though, I wanted to throw out some more general thoughts.

1. I'd like to manage this project like cattle, not cats.

   • This means as much automation as possible (i.e. dependabot).\
   • It also means we emphasize testing, so that we can be confident if a test suite passes, then dependabot can auto-merge dependencies (generally - there may be exceptions to dependencies we allow dependabot to manage).
   • Try to generate/templatize as much documentation as possible.

2. I'd like to utilize All Contributors to recognize contributors to the project.

   • A contribution doesn't necessarily mean code. It could be an idea, bug report, documentation, etc.

Purpose

The main purpose here is to provide a consolidated Java API for the docling interface. We'll start with the assumption that a docling serve instance is running somewhere and this API expresses a way to communicate with it.

• This API needs to be completely agnostic to any Java Framework (like Quarkus/Spring/etc).
• If we introduce functionality to call the API, we need to provide ways for downstream frameworks (like Quarkus/Spring/etc) to be able to customize it (like using Java's Service Provider Interface.

Design ideas

Base Java version

As much as I'd like to start higher, I think our Java baseline needs to be Java 17. That being said, our test automation should test against Java versions 17, 21, 25, and whatever the newest non-LTS version is.

Documentation

We need to have published documentation. I don't have any real preference over which documentation framework we use. I personally am most familiar with Antora, but I'm open to suggestions.

We should also try to ensure that anywhere we can auto-generate as much documentation as possible from the code (See # 1 above)

Project Structure

Should we set this up as a multi-module project from the onset to allow for maximum flexibility? We already know we're going to have a documentation module, so it probably makes sense, even if we're only publishing 1 artifact to maven central at first.

Maven Central

We need to set up release automation to automate releases. JReleaser is good. We have some things in the Quarkiverse that make it easy (just merge a PR to a version file and the release happens automatically). I'm open to other ideas too, but this needs to be fully automated.

Java package structure

io.docling4j would be a nice root package structure/groupId to use, but I think there is already a Docling4j project. What about any of these?

• io.docling.java
• io.docling-java
• io.docling.docling-java

I'm open to other suggestions as well.

Did I miss anything?

[ThomasVitale]

General

I agree on all points:

• as much automation as possible
• framework agnostic
• JReleaser for handling the release
• I would also go with Antora for documentation
• usage of All Contributors
• multi-module project.

I also have automation in other projects with JReleaser and Antora, and some ready-to-used templates/workflows.

For the package structure, I wonder if we could go with io.docling directly since the java part is kind of implied since it will be published in Maven Central. If that's not ok, I'd vote for io.docling.java.

About the Java version, it would be nice indeed if we could start with a higher baseline than Java 17. Would it make sense to consider Java 21?

Testcontainers

I would consider having one of the modules being a simple implementation of a Testcontainers module for Docling, extending from the GenericContainer API. Eventually, it could be moved upstream to the Testcontainers project, but in the meantime it would have two benefits:

• simplifying the automated tests for this project, including extracting the OpenAPI Spec for automated tests on that as well (from what I gathered, the spec is not published by Docling Serve, but it needs to be fetched from one of the endpoints, auto-generated by FastAPI);
• simplifying the integration for frameworks that will use this library, without the need to duplicate the implementation of a Docling Testcontainers module (with features like enabling the UI and logging the URL where it becomes available).

OpenAPI

Do we want to assess if it's possible to use the OpenAPI Generator as a starting point and try to see if we can solve the incompatibilities found in the OpenAPI spec generated by FastAPI?

Or do we want to start with the hand-written model similar to what I started here?

Either way, I have drafts for both solutions and I'd be happy to open an initial pull request.

[lordofthejars]

For me io.docling has sense, the Java part is something more redundant

[edeandrea]

@ThomasVitale

About the Java version, it would be nice if we could start with a higher baseline than Java 17. Would it make sense to consider Java 21?

I would love nothing more, but I also think we need to consider the larger community. Both Quarkus and Spring Boot (including SB 4 coming out in November) have a Java 17 baseline so I think we need to take that into consideration.

I also have automation in other projects with JReleaser and Antora, and some ready-to-used templates/workflows.

Great! Let's reuse as much existing stuff as possible.

Code Quality

I would love to use something like SonarQube or an equivalent, but I dont want to throw too much in front of an MVP either.

As we make some of these decisions (or at least have decisions that need to be made) we can create issues for them so we can track/implement them.

Testcontainers

I agree on all points. I think we should keep this in a separate module.

Do we want to assess if it's possible to use the OpenAPI Generator as a starting point and try to see if we can solve the incompatibilities found in the OpenAPI spec generated by FastAPI?

I spent probably an entire week on this recently trying many different approaches and could not get it to work.

The issue is that while syntactically correct, the OpenAPI document generated by docling-serve is not semantically correct. For example, there is lots of use of inheritance and polymorphism with discriminator values and the way it's described in the document isn't correct. It needs to define common types that can be extended from.

So if we want to go that route I think we'd first need to hand-craft a proper OpenAPI document. We can surely look at doing that, but I'd be hesitant because I wouldn't want it to diverge too much from what docling-serve is generating.

The ideal solution is if it could be fixed in docling-serve first and reused here. That would ensure version compatibility and would truly make everything contract-first. But @dolfim-ibm and the rest of the docling-serve team needs to buy-in to that.

This is a key decision point though and we should make it up front before we get started, as it will drive how the project moves from here.

[dolfim-ibm]

What you should consider the truth are the pydantic objects defined in the docling-core and docling-serve libraries. I would not trust any schema representation of those to match 100% the original design. Also, keep in mind the the Docling typing are defined according the pythonic best-practices, which might be different in Java.

You could also consider to use AI to translate those pydantic objects.

[edeandrea]

You could also consider to use AI to translate those pydantic objects.

What could possibly go wrong there? :D

Somewhat joking of course. We should look into it and if there is a way to (safely) do this via automation.

[dolfim-ibm]

A few governance aspects

When bootstrapping the repository, please adhere to the Docling Community governance. In particular:

1. Refer to the community governance https://github.com/docling-project/community
2. Add a CODE_OF_CONDUCT similar to the other repos, example https://github.com/docling-project/docling/blob/main/CODE_OF_CONDUCT.md
3. Add a CONTRIBUTING similar to the other repos, example https://github.com/docling-project/docling/blob/main/CONTRIBUTING.md (obviously adapting for Java development 😉 )
4. Short to medium term aim for at least the Silver status in https://www.bestpractices.dev
5. All functional accounts must be shared with the Docling TSC

[dolfim-ibm]

Practical points

1. We all agree and welcome automation.
2. For security reasons, GH actions follow the allow-list approach. If you need a new action to be included, please contact the Docling maintainers for reviewing it.

Regarding the points raised above, some suggestion

• Fully aligned in making it frameworks agnostic
• Namespace and package structure:
  • Consider the difference between the docling-core types (in the specific the DoclingDocument) which would deserve its own package and the API payloads of docling-serve. Should it be two packages? One with a clear structure?
    • We did something similar in https://github.com/docling-project/docling-ts
  • Is there a reason to prefer io.docling? The actual Docling domain would be ai.docling

[edeandrea]

@dolfim-ibm

Consider the difference between the docling-core types (in the specific the DoclingDocument) which would deserve its own package and the API payloads of docling-serve. Should it be two packages? One with a clear structure?

Noted. At a bare minimum we will separate using Java packages.

Do the core types and the DoclingDocument change independently? If so, we can consider separate submodules.

Is there a reason to prefer io.docling? The actual Docling domain would be ai.docling

I don't think I've ever seen a Java package name start with anything other than io., com., org., net., dev.. That doesn't mean it can't start with ai., but it isn't anything I've seen anywhere in industry. My preference would be io.docling, and then submodules define their own scopes under that (core, document, test, etc).

@ThomasVitale /@lordofthejars thoughts?

For security reasons, GH actions follow the allow-list approach. If you need a new action to be included, please contact the Docling maintainers for reviewing it.

Is there an existing list of actions that are already approved for use?

I don't mean to question things, but is there a particular reason for that? I've been working in OSS communities for a long time and have never come across such a requirement. I'm sure there will be many external actions that we will need to use. I just want to ensure that something like this won't block progress for days/weeks.

[dolfim-ibm]

We also known the docling.io domain, so for sure you don't get into somebody else 😉

[lordofthejars]

ai.docking as package could be something great and new.

[edeandrea]

ai.docking as package could be something great and new.

I've been thinking about this for the last few days and its actually growing on me. What do you think @ThomasVitale ?

[ThomasVitale]

For me ai.docling seems ok

[edeandrea]

@dolfim-ibm Is there an existing list of GitHub actions that are already approved for use?

Also, in the Actions permissions, can we please enable GitHub Actions can create pull requests or submit approving pull request reviews.? This is something we will need for our automation. It's currently greyed out and I can't enable it.

[lordofthejars]

Ok now that we have the structure, next great question, should we define the model using Open API documentation generated by docling-server (and live with the issues we might find) or we do like Thomas did and wecreate our own model.

[ThomasVitale]

It's fine by me. I can open a PR shortly just with the API classes and we could use it as a starting point.

[lordofthejars]

It is best to start working on it. Also, this will help in creating a Reference Implementation.

[edeandrea]

For a reference implementation, I'm thinking just a simple HttpClient. We'll need to figure out JSON marshalling. Would be nice to not need any external dependencies if possible, but if not, I think Jackson is what we use.

[lordofthejars]

I think HttpClient + Jackson is excellent. I know there are other options, but who uses JSON-B or any other? Most Java developers use Jackson, or at least have a background to understand what it does.

[ThomasVitale]

I've created an issue for this task: #17

And I've started preparing a PR with the models I already have in Arconia and some basic auto-tests. For now, I'm using Jackson, but we can always make it more generic later?

[ThomasVitale]

@edeandrea @lordofthejars what do you think about adopting Conventional Commits? It would help us produce nice and neat release notes automatically with JReleaser (and have a clean and readable git history). We could add an automated check on the PRs using https://github.com/Ezard/semantic-prs or something similar (if we're allowed to).

[edeandrea]

I think its a great idea

[edeandrea]

I've updated dependabot to prefix commits with chore:

[edeandrea]

I've also added this to the contributing guide.

[edeandrea]

I've also added the semantic-prs check

[edeandrea]

Take a look at https://github.com/docling-project/docling-java/blob/main/.github/semantic.yml and update accordingly.

[edeandrea]

@ThomasVitale Do you have an opinion on using Jackson 2.20.x vs 3.x? The bom and many of the artifacts have different maven coordinates and package names.

Generally I'm all for moving things to the latest versions, but if the idea for this project is that it will be extended by downstream frameworks (like Spring/Quarkus), I'm not sure those frameworks have adopted Jackson 3? This seems like its going to be a major headache throughout industry (like the javax.* to jakarta.* change).

[ThomasVitale]

Since this is a new project, I would adopt Jackson 3 for the default implementation of the client as that won't affect what the library/framework/application uses elsewhere for JSON parsing.

If libraries/frameworks want to provide their own implementation, then they'll have full freedom to choose how to handle the JSON parsing. If they want to use the default implementation, Jackson 3 can co-exist with Jackson 2 in the same application, so it won't constrain the library/frameworks in any way.

About the API, it shouldn't matter if we only use the Jackson annotations, since they are the same for both Jackson 2 and 3 (same coordinates, same dependency version). As long as we don't leak any Jackson implementation detail to the API, the model will be flexible enough to be used with both Jackson 2 and 3, as well as other JSON parsers.

Thoughts?

[ThomasVitale]

Additional comment: I guess we want to ensure this project can be used by libraries/frameworks/apps working with Jackson 2 as well as those working with Jackson 3. From that point of view, no matter what we choose, it probably needs to be compatible with both.

[edeandrea]

About the API, it shouldn't matter if we only use the Jackson annotations, since they are the same for both Jackson 2 and 3 (same coordinates, same dependency version). As long as we don't leak any Jackson implementation detail to the API, the model will be flexible enough to be used with both Jackson 2 and 3, as well as other JSON parsers.

Completely agree.