I accidentally sent a draft. To clear things up, I’ve opened OPENNLP-1888 to spark a design discussion around introducing a generic Document type into the 3.0 API.
Currently, our Java API is tool-by-tool; as we look toward adding more complex, structured results (like dependency arcs or relations), continuing this pattern means we'll end up building parallel surface areas for every new capability. The proposal in the JIRA ticket aims to solve this by introducing a small, unified container in opennlp-api that uses typed annotation layers over the original text. I want to emphasize right away that this deprecates and replaces absolutely nothing in the existing task-level API; it simply provides a clean, additive way to handle combined-document views moving forward. I'd really love it if we could take a look at the full architecture, constraints, and motivations in the ticket and share your thoughts. I think this design covers what you'd see in other APIs as well as some new frontier ideas. Thoughts? On Wed, Jul 15, 2026 at 3:17 PM Richard Zowalla <[email protected]> wrote: > Did this mail get mangled? > > > Am 15.07.2026 um 00:17 schrieb Kristian Rickert <[email protected]>: > > > > Two main points: > > > > - OPENNLP-1888 has not been started; it was created as a design > > discussion regarding a generic document shape I'm recommending. Details > in > > the ticket > > - Thank you everyone for the detailed feedback. I'll ensure every PR has > > a section in the documentation. > > > > OPENNLP-1888 was opened to discuss a generic Document type for the new > API > > interface. Details are in the ticket, but here is the initial shape and I > > would like anyone's thoughts on it: > > > > public interface Document { > > CharSequence text(); // the original text, > > never a normalized form > > <T> List<Annotation<T>> get(LayerKey<T> layer); // empty list when the > > layer is absent > > Set<LayerKey<?>> layers(); > > } > > > > public record Annotation<T>(Span span, T value) { } > > > > public final class LayerKey<T> { > > public static <T> LayerKey<T> of(String id, Class<T> type) { ... } > > } > > > > public interface DocumentAnnotator { > > Document annotate(Document document); // returns a new > document > > with layers added > > Set<LayerKey<?>> requires(); > > Set<LayerKey<?>> provides(); > > } >
