Skip to end of metadata
Go to start of metadata

Overview of "Annotate Resource in Registry" Use Case

Associate information with a resource

Tip: Key Points
UC Priority= 4 or 5: Critical, is in R2
Only boldface steps are required
<#> before a step —> lower priority
(optional) —> run-time option

Related Jira Issues:   Open   •   All


Refer to the Product Description and Product Description Release 2 pages for metadata definitions.

Actors Registered User
References UC.R1.12 Annotate Data
Is Used By UC.R2.22 Version Data Set
UC.R2.28 Manage Resource Metadata
UC.R2.23 Ingest Data Supplement
In Acceptance Scenarios AS.R2.01A Operate Marine Observatory, AS.R2.02A Cruise Support, AS.R2.02B Data Support via Cruise, AS.R2.02C Instrument Life Cycle Support, AS.R2.04A Data Product Leads Drive Core Data Product Creation, AS.R2.04B Curate Data Products
Is Extended By  
Technical Notes An annotation is an association of information to a resource, and requires all 3 elements (information, association, resource).
In R2 the user-accessible annotation capabilities are limited; while the system can create more annotations, these use cases do not strive to describe all the system-level features.
The actual design for adding comments to a resource will likely be implemented via Events; see Comments.
Lead Team DM
Primary Service OOI Common Data & Metadata Model Part 2
Version 1.7.1
UC Priority 5
UC Status Mapped + Ready
UX Exposure EUC


This information summarizes the Use Case functionality.

An annotating entity in the Integrated Observatory system creates the desired information to be applied, identifies the appropriate association (relation) to be made, and submits these with an identifier of the resource being annotated. The Integrated Observatory will register and maintain the annotation. The annotation can be viewed, either in its own right or in the context of the resource.


  • In R2, annotations are primarily generated internally.
  • Any resources can be annotated in principle, including information resources (such as data sets) and also executable resources, including resources representing physical entities (such as instruments).
  • An annotation does not change the original resource, but adds information (also known as attributes or properties) about the original resource.
  • A complete annotation involves all three components: the added information, the relevant relation, and a reference to the resource(s) to which it applies.
  • While it may appear possible to annotate the target resource with just a relation, not adding any other information (e.g., "testing_passed_on instrument_1"); for various reasons it is important that the relationship (the association) does not incorporate an actual resource or information set, even implicitly (instead, "test_2 passed_on instrument_1").
  • The first set of information can be a string or other data type (number, logical), and can also be a system resource (eventually, of any type).
  • An annotation is associated with the resource, such that it can be found by entities requesting the resource or its annotations

Initial State

A resource to be annotated is registered and activated in the Integrated Observatory system. The annotator (component or user) has an identifier of the resource, and has information which it wishes to associate with the resource.

Scenario for "Annotate Resource in Registry" Use Case

  1. User selects a resource in the Integrated Observatory
    1. This can be any resource accessible via ION interfaces
    2. Selecting the resource may be different by resource type
  2. User chooses to annotate the selected resource
    1. Annotating a resource is a generic functionality and should appear similar for all resource types
    2. Annotations may be of different nature. See variant steps in the Comments below
  3. User attaches a media object to the resource
    1. Media objects are binary attachments such as Word, PDF documents, JPEG images
    2. User selects attachment for upload.
    3. User may add a comment with the attachment
    4. The system may display the attachment using the resource metadata for a displayable attachment (e.g. image).
  4. User edits or removes annotation
    1. Depending on type of annotation

Final State

New annotation is created and available for search and retrieval


These comments provide additional context (usually quite technical) for editors of the use case.

Although this scenario anticipated that comments on a resource would be added in the form of attachments, the actual system design targets Events to hold comments. Thus, this use case no longer directly addresses the commenting activity.

These variants were removed from the scenario, as they are not performable by users in R2.

  1. (Variant 1) User associates a resource with another resource
    1. User selects a second resource
    2. User selects the type of association, e.g. "references"
    3. The user interfaces may be very limited or non existent. The system capability exists to perform this annotation.
  2. (Variant 2) User attaches additional metadata attributes to the resource
    1. These additional metadata attributes are not part of the primary set of resource metadata attributes
    2. User defines attributes (such as key-value pairs) for the resource
    3. The system may choose to display the additional metadata with the original resource attributes or separately
    4. The additional metadata may be a comment with timestamp and user id
    5. The user interfaces may be very limited or non existent. The system capability exists to perform this annotation.

This previous version of the scenario provides additional information about annotations.

  1. The information to be used in the annotation (typically the subject of the relationship) is organized into an internally represented object.
    1. An internal object that will hold the annotation resource must be created and registered in ion-objects
    2. If there are multiple pieces of metadata, separation of concerns suggest that multiple relations should be defined, rather than lumping all the information into a single relation. The usual design principles apply; in some cases it will make more sense for the information to be maintained as a composite object.
  2. The type of association (relation) which links the information to its targets is selected.
    1. The acceptable relations will essentially form part of an annotation vocabulary, a set of relations that can link the information to the resources.
    2. Initial relations are likely to include obvious associations like "isPartOf", "isDeployedOn", "describes".
  3. The complete annotation is created (submitted) by the annotator.
    1. This is machine-derived in R2, also human-derived in R3
    2. An annotation can include data in its own right; what makes it an annotation is the relationship to another information resource
    3. The target or object reference must be a precise description (a unique identifier recognizable to the system) of the resource (or subset or component of a resource) to which the annotation applies.
    4. The association is created and registered with associated metadata (creator, time stamp, ...)
  4. The annotation is searched and retrieved by annotation (association) type or object (target) resource.
  5. The annotation is modified to update the previous annotation.
    1. A new version of the association to the resource is created, specifying that it replaces the previous version.
    2. Old versions are not lost
    3. The information to be used in the annotation may or may not change; possibly only the relationship changes.

There are design decisions to be made about what resource metadata is accomplished via an annotation, vs stored structurally. As a design principle, it will make the most sense to store metadata in a predefined structure when the following conditions are likely to persist for the life of the system: that metadata is always or almost always present in a known cardinality, is typically set only once (or so often that changes need not be tracked, as in a counter), and is tightly coupled with the resource and its use in the system. As any of these conditions become less definitive, annotations provide the flexibility to accommodate design and usage changes more readily.

Annotations will be first-level resources. This means that they need their own unique identifiers, but that other annotations can be made about them. (Comments about comments are a typical useful capability that this enables.)

Finally, there is a very strong intuitive relationship between annotations and semantic relations. Using semantic best practices as a basis for the annotation design is likely to result in better usability of the annotations in the system, better interoperability in the wider world of linked data and the semantic web, and a wider range of future applications that can leverage OOI annotations. The experiences of semantic web development (good and bad) can directly inform the annotation implementations in ION.

(click on # to go to R2 use case)
01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60
61     27B


r2-usecase r2-usecase Delete
usecase usecase Delete
productdescription productdescription Delete
openissue openissue Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.