feat: idea for api design

[edeandrea]

An idea for api design. This still allows using Java records to implement the model objects, but also makes these objects backwards-compatible by introducing interfaces & builders.

NOTE I've only applied the pattern to the DocumentResponse so that we can decide if this is a good approach or not. If so, we can apply this pattern to the others.

FIxes #23

[edeandrea]

@ThomasVitale @lordofthejars take a look and let me know what you think of this approach. I didn't get into ServiceLoaders or anything like that. I think that overcomplicates things.

[lordofthejars]

Wow almost everything is done hahaha we are almost ready to go. Looks good to me just one small comment.

[lordofthejars]

Do we want to use the star import? I am not saying it isbad I am just wondering

[edeandrea]

Usually for * static imports my general rule of thumb (for myself at least) is that if its an internal class local to the codebase, then its ok, but if its pulling in 3rd party class/library then I tend to not import static *. Since ValidationUtils is part of the docling-java codebase (& It'll be used a lot) I tend to import static *.

I generally don't do any regular import *, only some import static *.

But I don't have a severely strong opinion on things. If @ThomasVitale @lordofthejars prefer never using import static * then thats fine too.

[lordofthejars]

It is good in my opinion, I was just raising for just in case IDE collapse the imports and you didn't notice

[ThomasVitale]

I generally avoid star imports, but I guess there's some rule in the .editorconfig file forcing them because I noticed that in my previous PR I got some star imports automatically applied, removing my explicit ones.

I'm fine either way, as long as we're consistent and we can automate the enforcement of whatever rule we decide to be compliant with.

[edeandrea]

Wow almost everything is done hahaha we are almost ready to go.

Well, not really :) This is just a design idea that I've only implemented for one of the model objects to show the idea/pattern. If we want to adopt this pattern then we need to implement it across the board.

Then we need documentation, release automation, etc :)

[lordofthejars]

Wow almost everything is done hahaha we are almost ready to go.

Well, not really :) This is just a design idea that I've only implemented for one of the model objects to show the idea/pattern. If we want to adopt this pattern then we need to implement it across the board.

Then we need documentation, release automation, etc :)

Perfect, looks good to me, then we erge this one and we adapt the rest of the model, or we push ito this PR?

[edeandrea]

Wow almost everything is done hahaha we are almost ready to go.

Well, not really :) This is just a design idea that I've only implemented for one of the model objects to show the idea/pattern. If we want to adopt this pattern then we need to implement it across the board.
Then we need documentation, release automation, etc :)

Perfect, looks good to me, then we erge this one and we adapt the rest of the model, or we push ito this PR?

If we like this model then I'll fill in this PR with the rest of the API (its currently marked as draft). I'd like Thomas to weigh in first though, since he was the one who built the initial version.

[ThomasVitale]

Thanks for this PR! In general, I like the approach, but I have two concerns:

• If we configure serialisers/deserializers in the API, then we are forcing the usage of a certain Jackson version and that might be problematic (I guess that was why Initial architecture & purpose #2 (comment)). If we stick to the annotations from the com.fasterxml.jackson.annotation package, they are the same across Jackson 2 and 3 (it's the only module that was not changed), so libraries will be free to use the API with their favourite version of Jackson (or even with another tool).
• I understand the idea behind the design based on interfaces and default implementation, but I'm a bit worried about the effort it would take us to maintain it manually. Existing generators like openapi-generator or openapi-processor don't have support for this kind of design (as far as I know), so even if we make the OpenAPI spec from Docling work, we might not be able to switch to the generated model in a straightforward way. I know that one of the reason for this design is to ensure backward compatibility, so I started a list of requirements in API Design #23 (comment) to help us decide on the final design. I have a hard time imagining situations where, as a library author, I would want to implement the interfaces myself for the data models (typically, it's the client interface that I would customise). But if that's a use case we want to support, let's add it to the list of requirements. What do you think? @edeandrea @lordofthejars