Hello all,
the target field of the annotation object is supposed to store the unit of content of a page to which the annotation applies: it can be the content of the page (when the target is the document reference) or a textarea field of an object of that page - in which case the target is a reference to that content.
The annotation API will also allow you to store in XWiki annotation objects that apply to an external content (with a different target reference).
The XWiki standard annotation UI will assume that all annotations that you add from the UI and that you request from the UI are on the content of the page the annotations UI is loaded for.
A custom UI or custom usage / implementation of the annotation API would allow one to store annotations differently.
The target is relevant mainly for the resolution of the annotation context (which is used to place annotations in the given content):
- the “contract” is that the annotation context (selection left + annotated text + right context) is unique within the annotation’s target;
- the automatic update of the annotation is supposed to update an annotation’s context when its target is updated (which restricts the number of annotations ‘checked’ on an update event, because the target is supposed to restrict them).
In terms of API, Annotations kinda need to have a target.
In terms of the implementation of that API for the storage of annotations of XWiki pages as XWiki objects, indeed the handling of the target can be improved for more flexibility:
- we could decide to add a semantic to an empty target field in objects, which would be “current page content”
- stop storing in the target field for new annotations, if they match the semantic above (their target is a page content and they get stored as an object of that page)
- normally all annotations manipulation should go through the IOService implementation, so updating the save & retrieval functions of the service to implement this should be enough.
Regarding migration, I think there should be one, which should empty targets only of they match the semantic above.
This looks a bit like your option 3 above, with a wiser “cleanup”, and I think it should not cause any regression if you don’t remove all targets wrecklessly.
So +1 for option 3 from me, with modifications.
I’m not sure I understand the first option: it’s about dropping the field altogether? It’s not a great idea, à priori, even if I don’t know of many cases of annotations stored with a specific target to a textarea field of an object, it’s possible, in theory (part of the current API).