Standardize annotations with Web services

Annotation is the process of associating metadata with data. This article presents a Web services API intended as an industry standard for client-server systems designed to facilitate the structured annotation of heterogeneous data. The author presents the goals of the Annotation Web services API and then discusses how those goals motivate the data model around which the API operates. The author also discusses 29 methods that comprise the API including two examples of possible sequences of API calls to create and retrieve annotations.

The Annotation Web services API is an implementation-neutral set of SOAP-based Web services calls intended as an industry standard to facilitate the interoperability of clients who wish to enable annotations and servers that store annotations and implement the API. The Web services Definition Language (WSDL) formally defines the syntax of the API. There are accompanying semantics in another document. This article explains the motivations behind the API’s design, as well as an overview of the API. You should consult the WSDL and accompanying semantic documentation for more information (see the Resources section below for links).

The word annotation has many different meanings depending upon the context and audience. Regardless of these differences, every annotation is essentially some metadata associated with some target data. The target data itself can vary from a table in a relational database, to a word processing document, or to the topic of what to cook for dinner tonight. The corresponding annotation might be an entry in another database table, a comment within the document, or a sticky note on the front of the refrigerator. Annotations are important when large amounts of data are created, shared, and examined. For example, the life sciences industry and the legal profession both make heavy use of annotations.

Everything but the refrigerator

Because of the substantial generality of annotations, the scope of the design must be narrowed in order to arrive at a useful and manageable Annotation Web services API. To accomplish this, the goals of a system must be enumerated based upon the Annotation Web services API and then derive the data model and API calls from those goals.

Annotate arbitrary digital data

The primary goal of the Annotation Web services API is to enable the annotation of any arbitrary digital data. Please note that the type, size, structure, or content of the data is arbitrary. For example, the same Annotation Web services API methods facilitate annotating both legal briefs and scientific experiment results.

Annotations stored out-of-band

The API should acknowledge the intrinsic existence and identity of data objects regardless of their names, locations, or any properties other than their contents. In other words, an annotation that you create on a memo on your local hard drive should be visible to your coworker with his or her own copy of the memo, despite potentially differing meta-information such as file name or timestamp. To accomplish this, the Annotation Web services API must encompass a model in which the annotations are stored separately from target data objects and in which data objects’ identities can be determined independently of file meta-information.

Structured annotations

Many applications include annotation functionality that follows the “sticky note” paradigm. Such annotations are better referred to as comments, as they consist only of free-form text entries. Even when centrally gathered, these unstructured comments are difficult to search or data-mine effectively and efficiently. Therefore, one goal of the Annotation Web services API design is the support of structured annotations — annotations containing information that conforms to a particular structure. Because a free-form text entry is simply one particular annotation structure, this design goal does not preclude unstructured annotations.

Other design goals

Several other goals also drove the design of the Annotation Web services API. Access control must be included to allow for private and semi-private annotations. The API must also facilitate bidirectional access between the annotations and the target data. The API also allows for maximum configuration, flexibility, and extensibility by implementors.

Source: IBM