DIAMs are forever ?

[Grégoire Montcheuil]

Dear INCEpTION (developers) team,

We are currently exploring the possibility to develop an "External Editor", with a custom document rendering using some document metadata and/or a special (hidden) layer of annotations.

We have a look to the External Editors section of the developer guide
  and to the INCEpTION Doccano Sequence Editor Plugin.
So we understand more or less that a good solution would be implementing a "document-rendering editor" that communicate with INCEpTION server using the DIAM Ajax API to get the document information and interact with the annotations.

Unfortunately, if the type(script) description in `inception-js-api/src/diam/DiamAjax.ts` help us to known the name and (input) data of the API, we have not (yet) found concrete documentation for this API.

It's true that some methods have a self-explanatory name, mainly the annotation manipulation ones (`createSpanAnnotation(...)`, `moveSpanAnnotation(...)`, etc. ).

But others are more cryptic (b.e. `loadLazyDetails(...)`, `triggerExtensionAction(...)`).

We also understand that the `loadAnnotations(...)` method seems a good entry-point to start the editor life-cycle (the doccanno sample call it two times)... and an important parameter is the format.
Thanks to the doccanno sample we known that "Brat" is one (core) accepted format, but is there somewhere a list of formats we can expect they are (and would remain) accepted ?

So we would appreciate if you could point us to more detailed documentation on the DIAM API.. and the way it will evolve and preserve compatibility.

Thank you in advance.

Best regards,

Grégoire Montcheuil

[Richard Eckart de Castilho]

Hello Grégoire,

> On 30. Mar 2026, at 13:29, Grégoire Montcheuil <gregoire....@gmail.com> wrote:
>
> Unfortunately, if the type(script) description in `inception-js-api/src/diam/DiamAjax.ts` help us to known the name and (input) data of the API, we have not (yet) found concrete documentation for this API.
> It's true that some methods have a self-explanatory name, mainly the annotation manipulation ones (`createSpanAnnotation(...)`, `moveSpanAnnotation(...)`, etc. ).
> But others are more cryptic (b.e. `loadLazyDetails(...)`, `triggerExtensionAction(...)`).

The lazy details are used by the annotation popover:

https://github.com/inception-project/inception/blob/main/inception/inception-js-api/src/main/ts/src/widget/AnnotationDetailPopOver.svelte

The extension action is a special action that is usually mapped to a double-click and which is provided by a potentially active

https://github.com/inception-project/inception/blob/main/inception/inception-api-editor/src/main/java/de/tudarmstadt/ukp/inception/editor/AnnotationEditorExtension.java

(e.g. curation editor extension, recommender editor extension, etc.)

> We also understand that the `loadAnnotations(...)` method seems a good entry-point to start the editor life-cycle (the doccanno sample call it two times)... and an important parameter is the format.
> Thanks to the doccanno sample we known that "Brat" is one (core) accepted format, but is there somewhere a list of formats we can expect they are (and would remain) accepted ?

You should use the format "compact_v2". If you want a pretty complete and modern implementation of an editor, look at the Apache Annotator editor in the INCEpTION codebase:

https://github.com/inception-project/inception/tree/main/inception/inception-html-apache-annotator-editor/src/main/ts (uses DIAM AJAX API)

It does not support relations though. You can look at the annotation sidebar or recogito editor for more inspirations including relations (recogito may be a bit outdated):

https://github.com/inception-project/inception/tree/main/inception/inception-diam-editor/src/main/ts/src (uses DIAM WebSocket API)
https://github.com/inception-project/inception/tree/main/inception/inception-html-recogito-editor/src/main/ts

The frontend API implementation is in:

https://github.com/inception-project/inception/tree/main/inception/inception-diam/src/main/ts/src/diam

The actual backend implementations are distributed over various Java classes, all implementing the EditorAjaxRequestHandler interface, e.g.:

loadAnnotations -> de.tudarmstadt.ukp.inception.diam.editor.actions.LoadAnnotationsHandler
https://github.com/inception-project/inception/blob/main/inception/inception-diam/src/main/java/de/tudarmstadt/ukp/inception/diam/editor/actions/LoadAnnotationsHandler.java
loadLazyDetails -> de.tudarmstadt.ukp.inception.diam.editor.actions.LazyDetailsHandler
https://github.com/inception-project/inception/blob/main/inception/inception-diam/src/main/java/de/tudarmstadt/ukp/inception/diam/editor/actions/LazyDetailsHandler.java

(for historic reasons, the actual command strings in the API/handler may look a bit odd, e.g. "normData" for the loadLazyDetails).

> So we would appreciate if you could point us to more detailed documentation on the DIAM API.. and the way it will evolve and preserve compatibility.

The API evolves occasionally as needed. I try to stay backwards compatible because that saves work updating the existing editors and examples ;)
The current wire format is "compact_v2" and it also has a bunch of shared decoder helpers in the JS API.
The API tends to be more stable then the wire format itself. I.e. implementations should rely on the
API and the shared decoder helpers for the compact_v2 format rather than implementing your own decoders.

https://github.com/inception-project/inception/tree/main/inception/inception-js-api/src/main/ts/src/model
https://github.com/inception-project/inception/tree/main/inception/inception-js-api/src/main/ts/src/model/compact_v2

Cheers,

-- Richard