# Working with annotations

Structured annotations permit the attachment of data and metadata outside the OMERO data model to certain types within the model. The annotations are designed for individualized use by both sites and tools. Annotations can be attached to multiple instances simultaneously to quickly annotate all entities in a view. Each annotation may have a “namespace” (`ns`) set. Tools can recognize specific namespaces and interpret those annotations accordingly.

## Annotated and annotating types

Each type which can be annotated implements `ome.model.IAnnotated`. Currently, these are:

- `Project`

- `Dataset`

- `Image`

- `Pixels`

- `OriginalFile`

- `PlaneInfo`

- `Roi`

- `Channel`

- `Annotation` and all annotation subtypes in order to form hierarchies

- ScreenPlateWell: `Screen`, `ScreenAcquisition`, `Plate`, `Well`, `Reagent`

- `Folder`

### Annotation hierarchy

Though they largely are all String or numeric values, a hierarchy of annotations makes differentiating between just what interpretation should be given to the annotation. This may eventually include validation of the input string and/or file.

    Annotation (A*) ....................... A name field and a description
      ListAnnotation ...................... Uses AnnotationAnnotation links to form a list of annotations
      BasicAnnotation (A*) ................ Literal or "primitive" values
        BooleanAnnotation ................. A simple true/false flag
        TimeStampAnnotation ............... A date/time
        TermAnnotation .................... A term used in an ontology
        NumericAnnotation (A*) ............ Floating point and integer values
          DoubleAnnotation
          LongAnnotation
      MapAnnotation ....................... A list of key-value pairs
      TextAnnotation (A*) ................. A single text field
        CommentAnnotation ................. A user comment
        TagAnnotation ..................... Interpreted as a Web 2.0 "tag" on an object, tags on tags form tag bundles
        XmlAnnotation ..................... An xml snippet attached to some object
      TypeAnnotation (A*) ................. Links some entity to another (possibly to be replaced by <any/>)
        FileAnnotation .................... Uses the Format field on OriginalFile to specify type

    A* = abstract

See also

Schema documentation for Structured Annotations

  Section of the auto-generated schema documentation describing the structured annotations

## Names and namespaces

Since arbitrary blobs or clobs can be attached to an entity, it is necessary for clients to have some way to differentiate what it can parse. In many cases, the name might be a simple reminder for a user to find the file s/he has annotated. Applications, however, will most likely want to define a namespace, like `http://name-of-application-provider.com/name-of-application/file-type/version`. Queries can then be produced which search for the proper namespace or match on a part of the name space:

    iQuery.findAllByQuery("select annotation from FileAnnotation where "+
     "name like 'http://name-of-application-provider.com/name-of-application/%'");

Tags will most likely begin without a namespace. As a tag gets escalated to a common vocabulary, it might make sense to add a possibly site-specific namespace with more well-defined semantics.

## Descriptions

Unlike the previous, `ImageAnnotation` and `DatasetAnnotation` types, the new structured annotations do not have a description field. The single description field was limited for multi-user scenarios, and can be fully replaced by `TextAnnotations` attached to another annotation.

    FileAnnotation fileAnnotation = …;
    TextAnnotation description = …;
    fileAnnotation.linkAnnotation(description);

## Examples

Examples of creating various type of Annotations can also be found on the Java and Python pages.

### Basics

    import ome.model.IAnnotated;
    import ome.model.annotations.FileAnnotation;
    import ome.model.annotations.TagAnnotation;
    import ome.model.core.OriginalFile;
    import ome.model.display.Roi;

    List<Annotation> list = iAnnotated.linkedAnnotationList();
    // do something with list

### Attaching a tag

    TagAnnotation tag = new TagAnnotation();
    tag.setTextValue("interesting");

    Roi roi = …; // Some region of interest
    ILink link = roi.linkAnnotation(tag);

    iUpdate.saveObject(link);

### Attaching a file

    // or attach something new
    OriginalFile myOriginalFile = new OriginalFile();
    myOriginalFile.setName("output.pdf");
    // upload PDF

    FileAnnotation annotation = new FileAnnotation();
    annotation.setName("http://example.com/myClient/analysisOutput");
    annotation.setFile(myOriginalFile);

    ILink link = iAnnotated.linkAnnotation(annotation)
    link = iUpdate.saveAndReturnObject(link);

All write changes are intended to occur through the IUpdate interface, whereas searching should be significantly easier through ome.api.Search than IQuery.

See also

Extending OMERO.server

Map annotations