Ontological term broker

Finding appropriate terms in an ontology and requesting new terms when needed currently requires too much time-consuming ad hoc coordination with ontology maintainers. We describe the design and implementation of an ontology broker, a software system that mediates interactions between an document annotator and an ontology maintainer. The broker is a web service for annotation software, used by the annotator, to find existing ontological terms and to create requests for new terms using provisional identifiers. The broker accepts requests for new ontology terms in a way that does not depend on the immediate availability of the ontology maintainer. The broker is managed by a governor, who sets policies of a particular broker including what kinds of requests it will accept and (where necessary) which ontologies those requests will be assigned to.

This document will describe who can use the broker, outline the details of the interface to the broker, and provide a description of an implementation of that interface.

Motivation
A document annotator is a person who searches through the text of a document in order to attach terms from a target ontology to a piece of that text. In the absence of a broker, the document annotator must manually search for matching terms in the ontology. Annotation software can assist this process, by indexing and searching multiple ontologies and returning matches to parts of the source document. The annotator may then choose one or more of these terms in order to create an annotation matching text to term. However, if no appropriate matching term is available, the annotation software can be of no additional use. The document annotator must separately request a new term from a maintainer of the target ontology. If this request is fulfilled, and a new term created by the maintainer, the annotation software can then be re-used on the new, enlarged ontology in order to find the correct term.

Interfaces to ontology maintainers for new term requests are currently ad hoc (email, face-to-face communication), or require the annotator's individual attention and input (web forms and bug-tracking systems). The document annotator must use these interfaces to negotiate the creation of a new term with the ontology maintainer. This is a slow process, prone to error for complex requests and dependent on the availability and responsiveness of the ontology maintainer. If the annotation of a document requires a new term, and if the request and creation of that term in the ontology takes days or weeks, then every document which requires that term for annotation must remain incompletely annotated during that time.

The ontology broker separates these interactions, allowing annotation software to make new term requests automatically and immediately receive "provisional identifiers" to be used in annotation. The ontology maintainer also interacts with the broker, giving new ontology term identifiers for requests which can be fulfilled and requesting more information on incomplete or ambiguous requests. The broker has a 'governor,' who maintains administrative control over the broker and who sets any broker-specific policies including which requests are accepted and which ontologies can have terms requested from them.

Context for the Use of a Broker
The broker mediates a document annotator's use of an ontology and, when necessary, communication with an ontology maintainer. To understand where the broker can be helpful, we describe the typical tasks of both the document annotator, the ontology maintainer, and the individual (governor) who is in charge of managing the broker itself.

Document Annotator Tasks
A document annotation is a relation linking a part of a source document to a term from a target ontology, and a document annotator is a person who examines a source document and creates document annotations for parts of that document. The word annotation can also be used to describe the process of creating document annotations by a document annotator.

The annotator:
 * chooses a source document,
 * determines a part of the document to annotate,
 * searches for a term from the target ontology corresponding to the document part,
 * if there is no appropriate term in the ontology, requests that a new term from the ontology maintainer,
 * when a new term has been granted by the ontology maintainer, checks to see if the new term matches the intent of the original request, and
 * creates an annotation pairing the chosen document part with the target ontology term.

An example of a document annotator would be a user of the MGH Annotation Framework software.

Annotation Software Tasks
Annotation software is computer software that assists the document annotator in performing the tasks listed above. Typical annotation software simultaneously displays both the source document and existing annotations of that document to the annotator, and allows easy search for existing terms in one or more target ontologies.

The annotation software:
 * loads and displays the source document,
 * permits the selection of text to be annotated,
 * allows the annotator to search a target ontology by term name, description, or other metadata,
 * provides term matches to the annotator for choice of a correct target term, and
 * records chosen annotations of the document.

Example of annotation software are the MGH Annotation Framework software and the Antibody Record Annotation software.

Broker Governor Tasks
An annotator may not be able to determine an ontology for a request, either because they are not sure which ontology the term belongs in, or because there is no ontology that the broker manages that the term is in the domain of.

For example, the annotator may find a block of text that she wishes to annotate, but is unable to find a matching term in the broker and is unclear which ontology, supported by the broker, would be appropriate for receiving the new term request. The annotator may submit the request to a broker governor to help resolve such situations.

This broker governor is responsible for the broker, adding information about ontologies to the broker such as maintainer, understanding the scope of the broker's current ontologies, and being able to respond to requests for information about which ontology a term request should be directed to.

The governor should be able to pick up all the requests that do not specify an ontology and address them in the following ways:
 * direct the term to the correct existing ontology. The maintainer of that ontology will take over from there
 * configure the broker for a new ontology (and related maintainer) that will accommodate that term. The maintainer of that ontology will take over from there
 * reject the term request as inappropriate for the broker.

Ontology Maintainer Tasks
An ontology maintainer is a person assigned with creating and updating a particular ontology, a scientist or knowledge engineer who has responsibility for maintaining an ontological document.

An ontology maintainer:
 * creates new terms and relations in an ontology for which she is responsible,
 * associates metadata' with terms (proper names, definitions, synonyms, examples of usage, comments),
 * creates relations between terms (e.g. forming a term taxonomy using the is_a relationship),
 * receives requests, derived from particular documents (provenance, context), for new ontology terms,
 * fulfills those requests with new terms that are then made part of the ontology, or
 * rejects those requests for insufficient or ambiguous information, or for inappropriate intent (requesting a term from the "wrong" ontology).

An example of an ontology maintainer would be Darren Natale, or another representative of PRO.

Term Request Example
The ontology broker provides a programmatic API for the primary tasks of the annotator, annotation software, and ontology maintainer. In particular, as described in the Motivation section, we focus on the "requesting" task of the annotator and the "fulfilling requests" task of the ontology maintainer -- these are two sides of the same interaction, a synchronous conversation where each party must wait for the other to respond before proceeding.

The core function of the ontology broker is to provide an HTTP interface, for the annotation software and the ontology maintainer, to make each side of this interaction asynchronous and allow both parties to accomplish their respective tasks without requiring immediate availability and response from the other.

In this section we give a basic outline of the broker's request interface and how it separates the two sides of this interaction into asynchronous communications. We describe how the broker uses a system of provisional identifiers as placeholders for the terms that will eventually be used to satisfy each request. Annotation software can use these provisional identifiers immediately, as long as it obeys a contract to later check the status of the identifier and substitute the original provisional identifiers with the granted ontological terms.

The following shows a sample annotator/maintainer interaction using the broker, and should be read from left-to-right as a sequence of interactions with the broker by the annotation software and ontology maintainer.

A successful request which is ultimately fulfilled with a new term by the maintainer can be broken down into six steps.
 * 1) Annotation software makes a request for a new ontology term (at direction of the annotator).
 * 2) Additional term requests are made, and provisional identifiers created, as needed by the annotator.  The broker accumulates a list of pending term requests.
 * 3) At a later time, the ontology maintainer asks for the list of all pending requests, and receives them in bulk (as a spreadsheet or comma-separated value file).
 * 4) The ontology maintainer examines the requests, creates new ontology terms to satisfy the requests, and uploads them (using the same bulk file format) back to the broker.  The broker marks each pending request for which as new ontology term has been created as "fulfilled."
 * 5) At a later time, the annotation software checks on the status of a provisional identifier that was granted earlier by the broker.  If the corresponding request has been fulfilled in the meantime, the broker returns the new ontology term in response.
 * 6) If the annotator or annotation software determines that the granted term matches the original intent of the request, the annotation software replaces the provisional identifier with the final ontology identifier in its source document annotations and indicates to the broker that it "agrees" with the final ontology term.

This is the simplest example of a request-and-fulfillment between the annotator and the ontology maintainer using the broker. The interface to the broker also includes options for handling different sorts of errors that are not illustrated here. This interface should handle not only situations in which the communications (from either the annotation software or the ontology maintainer) are syntactically incorrect, but also situations In these cases, the broker provides methods for the annotation software and ontology maintainer to (asynchronously) communicate these judgements.
 * where the request itself is insufficient for the ontology maintainer to create a new term (JAR says: this needs to be expanded or explained, possibly with examples ), or
 * where the annotator determines that the ontology term which was granted does not match the intent of the original request.

The broker takes responsibility for enforcing minimal formatting and metadata requirements on term requests from the annotator, and for delivering a list of pending requests for editing and fulfillment to the ontology maintainer. It will refuse to accept new requests that are poorly formatted or that lack metadata which the ontology maintainer has deemed to be required. The broker delivers lists of pending term requests to the maintainer in a spreadsheet or flat-file format which is easily editable, and takes bulk responses from the maintainer by parsing an extended version of the same format. More details of these interactions are provided in the later sections which describe the broker's interface in more detail.

Requests
The example request-and-fulfillment process outlined above shows that the broker's primary activity is the storage and update of requests. Each request is created in response to an interaction by the annotation software, passed to the ontology maintainer, matched with a new ontology term from the maintainer's response, and passed back to the annotation software.

However, the tasks outlined above for the annotator, annotation software, and ontology maintainer suggest that not every request can be created and fulfilled in exactly this simple manner. Some requests will be created with insufficient or ambiguous metadata, and it is a task of the ontology maintainer to identify these problematic requests and require clarification from the annotator. Some requests may be insufficiently fulfilled by the ontology maintainer; these requests must be flagged, by the annotator, as insufficient for the annotator's needs. These additional interactions must be threaded through the three-part asynchronous "request-fulfill-check" interaction used by the annotation software and ontology maintainer in the example above.

We handle these additional kinds of interaction between annotators and ontology maintainers by introducing a status for every request. As each request is initially created in the broker, it is given an initial "pending" status -- this marks it as requiring review by the ontology maintainer when the maintainer next contacts the broker. As each request is matched with a new ontology term by the maintainer, its status is changed to "fulfilled." This marks the request as ready to be passed to the annotation software, when the annotation software next checks the provisional identifier originally granted to that request.

All the other states and interactions between the broker and the annotator or maintainer can be described by creating new request statuses, each of which encodes the last change made to that request and the next interaction required in order to move the request forward.

The following is a comprehensive list of all request statuses used in the ontology broker.
 * PENDING : a pending request awaits review by the ontology maintainer. Every request is initially given a provisional identifier (which is passed back to the annotation software) and stored in the broker with the PENDING status.  ERROR or INCOMPLETE requests are marked as PENDING when they have received an update from the annotator.  Requests which are FULFILLED or REDUNDANT are given the PENDING status when the original requester determines that the granted ontology term does not match the original request's intent.
 * FULFILLED : A term request that has been reviewed and granted a new term in the ontology is given the FULFILLED status. Requests which are FULFILLED are awaiting review by the annotator -- if the granted term is judged to be acceptable the request is given the terminal AGREED status, otherwise, it is marked as PENDING further review.
 * REDUNDANT : When a term request has been reviewed and an existing term from the ontology is found by the maintainer to match that request, the identifier for the existing term is matched to the request and the request is given the REDUNDANT status. Redundant terms, like fulfilled terms, must be either agreed with, or disagreed with, by the annotator before moving to either the AGREED or PENDING status.
 * AGREED : A term request which was matched to a new term (FULFILLED) or existing term (REDUNDANT) is marked as AGREEDA when the annotator who originated the request agrees that the given ontology term judges the given term to correspond to the intent of the original request.
 * WITHDRAWN: Any term request except for one in the AGREED state may be, at any time, withdrawn by the original requester. A withdrawn request requires no further interaction by either annotator or maintainer, and will not be used to satisfy any text queries.
 * INCOMPLETE : If a term request has a required field which has not been filled out, the ontology maintainer give it the INCOMPLETE status. This requires requires additional update from the request submitter before being marked as PENDING further review.  The definition of "incomplete" may be ontology-specific and may depend on optional metadata which is missing for a particular request; e.g., a well-formed request for a "modified protein" which fails to add any metadata indicating the location of the modification would be marked as incomplete by the maintainer of a protein ontology.
 * ERROR</tt> : A request that has been submitted in error (for example, a request for a term from one ontology that should be requested from a different ontology, such as a request for a gene from a protein ontology), or that contains a mistake in its description (e.g. a well-formed request for an isoform of a protein is not empirically supported) is given the ERROR status.  These requests may still be updated by the original annotator; for example, an "unknown isoform request" may be simply the result of a typo in the original request.  Any request marked as ERROR must have its fields updated by the submitter before further review is possible.
 * ESCALATE</tt>: when review by the maintainer determines that no further interaction through the broker will be possible, the request is marked as "escalate," and the term submitter is suggested to contact the ontology maintainer directly.
 * ESCALATED-TO-GOVERNOR</tt>: at any time, the governor may determine that the request has been wrongly submitted to an ontology, or should be transitioned to another ontology on the same broker, or some other action (external to the broker) should be taken. The request is placed into this ESCALATED-TO-GOVERNOR state, where it can only be updated by the governor.  Eventually a course of action is chosen, and the request is transitioned back to either the PENDING state or to the ERROR state.

Requests that have the last two statuses, AGREED or WITHDRAWN, are "terminal" -- no additional action by the annotator will cause the request to be re-reviewed using the broker.

We can summarize the request statuses, and the actions required from either the annotation software or the ontology maintainer to change the status of a request, with a request state diagram. Transitions are labeled by the broker function and colored according to who invokes the function; the exact transition taken in each step depends on the parameters to the function).

''This diagram is getting a little unreadable and hairball-like. I've tried to draw it a second time in a slightly different (more flowchart-like) style, below. I'd appreciate comments on which of these styles is preferable (or possibly if there is an altogether different way to draw it? --TWD''



<font style="color: red;">AR and PC think that there should be a transition to ESCALATE from AGREED/DISAGREED, and from ERROR/INCOMPLETE as well.



/Old State Transition Diagram

Note: this is a diagram of request statuses and transitions, and does not represent protocol errors (e.g. a malformed REQUEST call from the annotator, or a RESPONSE from the maintainer that references a non-existent request, etc). These will be covered in the protocol description, below.

Functional Requirements
In the previous sections we have outlined the tasks that the annotator, annotation software, and ontology maintainer must perform, and we have described how the ontology broker can break the requirement of synchronous communication between annotator and ontology maintainer by creating term request, fulfillment, and checking interfaces. We have described how request statuses, annotator request updating, and the ability to agree or disagree with fulfilled requests can resolve ambiguous communication from either annotator or maintainer.

We expect that most of the searches will retrieve at least one appropriate term from the ontology and will not require a new term request and provisional identifier from the broker. Finally, we expect that new terms which are identified and requested will not be unique but will often occur several or many times across one or more source documents.

This task and two expectations suggest searches receive in response existing ontology terms or term requests already created within the broker that match the search phrase. In this way, we can avoid excessive creation of redundant term requests and also provide an easy interface for the annotation software to find existing terms in the ontology. So the broker should index both the existing ontology and the PENDING</tt> term requests; either can be returned as result of a search.

In this section we outline the complete set of functions which can be invoked on the broker, by either the annotation software or the ontology maintainer, in order to carry out these interactions.

AlanR: Please include a plausible example of each request.

/Paolo's Priority List

Annotator Methods
The broker must allow the annotation software to search for old terms and new requests, to create requests, to update those requests in response to status messages from the maintainer, to check on the status of existing requests, and to agree or disagree with those requests which have been marked FULFILLED</tt> or REDUNDANT</tt>. In order to satisfy these requirements, the broker makes the following set of functions available to the annotation software.

Parameters, errors, or behaviors marked in <font style="color: red">red indicate those features that are not implemented in the test-server according to this spec.

The "*" suffix on a parameter type indicates that the parameter may take a list of zero-or-more values of that type; e.g.  "ontology_id : number* </tt>" indicates that the ontology_id</tt> parameter is passed zero or more number values.

CHECK-GOVERNOR</tt>
Gives the contact information about the governor of the ontology broker.
 * 1) Required Parameters: None
 * 2) Optional Parameters: None
 * 3) Response: A response containing the name and contact information for the broker's governor.

LIST-ONTOLOGIES</tt>
Lists the available ontologies against which requests may be made using this broker.
 * 1) Required Parameters: None
 * 2) Optional Parameters: None
 * 3) Response: A list of Ontology descriptions, including contact information for the maintainer of each ontology.

QUERY</tt>
Search for an existing term or pending query
 * 1) Required Parameters:
 * 2) search : string </tt>
 * 3) context : string </tt>
 * 4) Optional Parameters:
 * 5) ontology_id : number* </tt>
 * 6) Response: List of Search responses.
 * 7) Note: Each search response contains either an existing term or request with status PENDING or ESCALATE, with name or metadata that match (by text) the given search value.  Queries responses will only match terms from, and requests to, the indicated ontologies if the optional ontology_id</tt> parameter is given.
 * 8) Errors:
 * 9) Bad Request : if the search</tt> parameter is missing, or if any parameters are poorly formatted.
 * 10) Gone : if the ontology_id</tt> parameter is given, but the value does not correspond to any known ontology.
 * 11) Examples
 * 12) Annotator sends the query text "MAPT" to the broker, and the broker responds with "PRO:000010173", the PRO term for microtubule-associated protein tau.
 * 13) Annotator sends the query text "Tau pThre215" to the broker.  A different user has already requested a new term for "Tau pThre215", a form of microtubule-associated protein tau which is phosphorylated at the threonine in position 215 of the full-length form, and was granted the provisional identifer "TMP:000001" for their request.  The broker responds with "TMP:000001" to the annotator.

<tt>REQUEST</tt>
Create request for a new term.
 * 1) Required Parameters:
 * 2) <tt>search_text: string </tt>,
 * 3) <tt>context : string </tt>,
 * 4) <tt>provenance : string </tt>,
 * 5) Optional Parameters:
 * 6) <tt>metadata : &lt;string,string&gt;* </tt> (key-value pairs which are appended to the Request as metadata)
 * 7) <tt>ontology_id : number </tt>
 * 8) Response:
 * 9) <tt> string </tt> : a provisional identifier for the term.
 * 10) Errors:
 * 11) Bad Request : if any required parameters are missing, or if any parameters are poorly formatted.
 * 12) Gone : if given <tt>ontology_id</tt> is doesn't correspond to known ontology.
 * 13) Note: If <tt>ontology_id</tt> is not indicated, a "default ontology" is chosen for creating the request.
 * 14) Examples:
 * 15) Annotator requests a term for "Tau N2 R3, an isoform of microtubule-associated protein tau that lacks Exon 10 of the full length form."  Additionally, the annotator appends a block of text ("context") in which this description was found, and a link ("provenance") to the document from which this context was taken.  The annotator optionally adds structured metadata, for instance, that this is a request for an "isoform", or the coordinate range of the exon missing from this particular isoform.  The broker repsonds with the provisional ID "http://ashby.csail.mit.edu:8080/request/10/".  This URL, when GETted using HTTP, returns a JSON-formatted data object corresponding to the information submitted as part of the request, along with the request's current status.  When the request has been updated to FULFILLED, this URL may redirect to the corresponding final ontology URL.

<tt>UPDATE</tt>
Update Request in response to ontology maintainer feedback
 * 1) Required Parameters:
 * 2) <tt>provisional_id : string </tt>
 * 3) <tt>metadata : &lt;string,string&gt;* </tt> (key-value pairs, which are appended to the Request)
 * 4) Response: "Ok"
 * 5) Errors:
 * 6) <font style="color: #ff0000;"> Unauthorized : if the caller is not authenticated as the creator of the request specified by <tt>provisional_id</tt> [PC: Priority Level 3]
 * 7) Forbidden : if the request is in states AGREED, WITHDRAWN, PENDING, or ESCALATE.
 * 8) Bad Request : if any required parameters are missing.
 * 9) Examples:
 * 10) Original request for "human Tau" is marked as INCOMPLETE by maintainer, because it lacks metadata describing the appropriate organism name and taxon.  The annotator UPDATES the request, adding two new key-value metadata pairs: &lt;"taxon","9606"&gt; and &lt;"organism","human"&gt;.  The UPDATE is accepted, the metadata are appended to the request description, and the request status is changed back to PENDING.

<tt>CHECK</tt>
Check stat of term request
 * 1) Required Parameters:
 * 2) <tt>provisional_id : string </tt>
 * 3) Response
 * 4) Request description
 * 5) Errors:
 * 6) Gone : <tt>provisional_id</tt> is missing or doesn't correspond to any known request.
 * 7) Examples:
 * 8) The annotator has submitted a request, and was returned the provisional ID "http://ashby.csail.mit.edu:8080/request/10/".  At a later date, the annotator wishes to discover the status of the request; the annotator CHECKs the request by issuing an HTTP GET against the URL.  The response is a JSON object indicating the information associated with the request (including its status), or an HTTP redirect to the final ontology URI if the request has been FULFILLED.

<tt>JUDGE</tt>
Judge a fulfilled or redundant request as either "agreed" or "disagreed."
 * 1) Required Parameters:
 * 2) <tt>provisional_id : string </tt>
 * 3) <tt>judgement : string </tt>
 * 4) Optional Parameters:
 * 5) <tt>comment : string </tt> : the key value pair "comment","[string]" are appended as metadata to the given request, if the JUDGE action succeeds.
 * 6) Note: the <tt>comment</tt> parameter is optional if <tt>judgement=AGREE</tt>, but required if <tt>judgement=DISAGREE</tt>
 * 7) Response: "OK"
 * 8) Errors:
 * 9) Bad Request : if <tt>judgement</tt> does not equal either "AGREED" or "DISAGREED", or if <tt>judgement</tt> is "DISAGREED" but there is no <tt>comment</tt> parameter given.
 * 10) <font style="color: #ff0000;"> Unauthorized : if the caller is not authorized as the creator of this request. [PC: Priority Level 3]
 * 11) Gone : if the <tt>provisional_id</tt> does not correspond to a known request.
 * 12) Examples
 * 13) A request for "APP 770" with provisional id <tt>http://ashby.csail.mit.edu:8080/request/12/</tt> is granted a new term in the PRO ontology, with identifier <tt>PRO:00000NNNN</tt>.  The annotator who created the request CHECKs that provisional identifier and is given the granted identifier, along with the indicator that the request has been converted to <tt>FULFILLED</tt> status.  The annotator verifies (offline) that the description of the granted PRO term corresponds to the APP 770 isoform by definition and database reference (eg. Uniprot), and then calls the JUDGE function on the broker with the parameters <tt>http://ashby.csail.mit.edu:8080/request/12/</tt> and "AGREE".  The request is converted to the <tt>AGREED</tt> status.

Maintainer Methods
The broker allows the ontology maintainer to download a complete set of <tt>PENDING</tt> requests through a bulk download interface that produces output in the Bulk Request File Format. It also allows the maintainer to modify requests in bulk by uploading a modified form of the same file -- each request in the file is given a new status through individual data columns appended to its row in the bulk file format. In order to satisfy these requirements, the broker makes the following functions available to the ontology maintainer:

<tt>LIST-USERS</tt>
Lists all user accounts that are able to create requests against an ontology using this broker.
 * 1) Required Parameters: None
 * 2) Optional Parameters:
 * 3) <tt>ontology_id : string </tt>
 * 4) Response: A list of User descriptions.
 * 5) Errors:
 * 6) Gone : if the <tt>ontology_id</tt> parameter is given, but the value doesn't correspond to any known ontology.

<tt>ADD-ONTOLOGY-FIELD</tt>
Adds a bulk-data request field to an Ontology.
 * 1) Required Parameters:
 * 2) <tt>ontology_id : string </tt> -- the ontology to which to add the field.
 * 3) <tt>field_name : string </tt> -- the name of the field (becomes a column in the bulk request file)
 * 4) <tt>field_description : string </tt> -- a human readable description of the field
 * 5) <tt>metdata_key : string </tt> -- the key of the Metadata object (part of the Request) whose value is used to populate this field.
 * 6) Optional Parameters: None
 * 7) Response: OK or Exception
 * 8) Exceptions:
 * 9) Gone : if the <tt>ontology_id</tt> doesn't correspond to any known ontology.

<tt>LIST-REQUESTS</tt>
List requests
 * 1) Required Parameters: None
 * 2) Optional Parameters:
 * 3) <tt>ontology_id : number </tt>
 * 4) Response: file, in the bulk file format, of all requests which contain the pending status.  If the optional ontology identifier is given as an argument, than only those requests which are pending for this ontology are listed in the file.
 * 5) Errors:
 * 6) Bad Request : if a given <tt>ontology-id</tt> doesn't correspond to a known ontology.

<tt>RESPOND</tt>
Respond to term requests in bulk.
 * 1) Required Parameters:
 * 2) <tt>ontology_id : number </tt>,
 * 3) <tt>file : modified bulk request file </tt>
 * 4) Optional Parameters: None
 * 5) Response: "OK"
 * 6) Errors:
 * 7) <font style="color: #ff0000;"> Unauthorized : if the caller isn't authenticated as the Ontology Maintainer for this ontology.  [PC: Priority Level 3]
 * 8) <font style="color: #ff0000;"> Request Entity Too Large : if the uploaded bulk request file is "too large". (Question: how big is too big? -TWD)  [PC: Priority Level 3]
 * 9) Forbidden : if the file contains an update which is illegal given the current status of the request.
 * 10) Conflict : if one of the requests has been changed since the time the bulk request file was obtained (discovered by comparing the metadata of the request in the file to the metadata of the request in the broker's database).
 * 11) Note: bulk file format should include a "comment" field which is required when the decision is not FULFILLED or REDUNDANT.

Protocol Exceptions
The following exceptions are used in the function descriptions, above.
 * 1) Bad Request
 * 2) Unauthorized
 * 3) Forbidden
 * 4) Gone
 * 5) Request Entity Too Large
 * 6) Conflict

The following exceptions may be useful in the future.
 * 1) Method Not Allowed
 * 2) Unsupported Media Type

Each request is accompanied by a human-readable description of the error that occurred to be displayed by the annotation software to the annotator (or directly displayed to the ontology maintainer).

Use Cases
PC: Probably a UML Sequence Diagram for each case would help readability

''Here's my shot at a very basic version of UML sequence diagram for the simple "request-fulfilled-approve" case described above. Paolo and Alan, if you could review this and make any comments or suggestions? I want your approval before I go churning out a large number of these things. Also think about where these diagrams could go... --TWD''

Escalate
''Here is a second diagram, for the "ontology maintainer escalates the request" use case. -- TWD''



''PC: update the picture making sure the humans and software elements are well distinguishable

Error / Incomplete
The obvious third use case example diagram is the "ERROR" or "INCOMPLETE" request diagram.



Installation
A test broker implementation is provided in the Neurocommons Subversion repository.

http://svn.neurocommons.org/svn/trunk/broker/

Check included file <tt>INSTALLATION</tt> for notes on how to install and run the broker.

URLs
The protocol above is implemented by mapping each method invocation to an HTTP request against a known URL. The following URLs will be used:
 * <tt>/requests</tt>
 * <tt>/request/*/</tt>
 * (the URL <tt>http://[host]/request/*/</tt> is the provisional identifier granted by the broker for term request with internal id <tt>*</tt>)
 * <tt>/query</tt>
 * <tt>/bulk-requests</tt>
 * <tt>/ontologies</tt>
 * <tt>/ontology/*/</tt>
 * <tt>/ontology/*/fields</tt>
 * <tt>/users</tt>
 * <tt>/user/*/</tt>

The first three URLs are for use by the annotator, and the final URL (<tt>/bulk-requests</tt>) is the access point for the ontology maintainer.

Data Structures
Descriptions and schemas for the different types of structured data which are passed to the broker as parameters, or returned in the responses from the broker.

Relational
/BulkRequest

/BulkResponse

JSON
The web-service communicates by taking JSON objects as arguments to its methods, and by returning JSON objects as values from those methods. We describe the core JSON objects used by the broker here, using the JSON Schema notation.

/Requests

/Metadata

The <tt>ontology_id</tt> and <tt>user_id</tt> values are keys to individual Users and Ontologies. Users are tracked as part of the provenance, permissions, and logging of the system; by default the <tt>user_id = 1</tt> user is the "anonymous" or "unknown" user. Ontologies are referenced separately for the purpose of supporting (if necessary) requests for multiple ontologies within the same broker in the future.

Both data structures and interfaces are defined on other pages:

/User Objects

/Ontology Objects

/Ontology Field Objects

/Search Results

/Governor Contact Information

HTTP Methods
The following table describes the mapping of broker methods to HTTP queries:

Exception Handling
''Need to add a note on how exceptions and errors in the protocol are represented and returned to the user. --TWD''

Errors are signaled by returning a response with an appropriate HTTP 4xx Status Code, whose body contains a JSON-formatted "error object" containing both the type of error and description of the specific circumstances under which the error occurred.

/Error Object

Authentication
''We need to have a plausible story for user creation, authentication, and permissions. Alan suggested OpenID, but since some of the choices here depend on the way that the MGH Annotation Framework software here is built, I need guidance from Paolo or someone else. --TWD''

Java Server Software
''I think there should be a brief description of the components of the implementation. How is the state maintained - a database of some kind? What language is the thing programmed in? (Java) What web platform is proposed? (servlets? .war file running in any servlet container?) Does it break down into nontrivial modules? Block diagram of pieces maybe?''
 * Not sure what's being asked for here. I've [[Media:Broker-block-diagram.png|tried]] diagramming out some components of the system as its implemented currently, but I'm not sure that's very readable or any more useful than a simple table? --TWD

''PC: also a description of the components will help attributing functionalities to the different pieces and measuring what is implemented and what is missing.

The sourcecode for the Java implementation of the Broker protocol, using servlets and JSPs, is in the Neurocommons subversion repository.

This implementation includes a browser interface for debugging and simple interactions, written in HTML+Javascript+jQuery.

Servlets
A list of the Servlets that are part of the Broker implementation, and an outline of which methods of each Servlet handle which types of Broker functions.

<font style="color: red;">This servlet list is old -- this description needs to be revised to match the current implementation.


 * RequestServlet
 * doGet : CHECK
 * doPost: UPDATE, JUDGE
 * RequestListServlet
 * doPost : REQUEST
 * doGet : lists all requests, with optional filtering parameters
 * DBObjectServlet
 * doGet : returns data on individual Users and Ontologies
 * doPost: handles modifications to individual Users and Ontologies
 * DBObjectListServlet
 * doGet : LIST-USERS and LIST-ONTOLOGIES
 * doPost : adds new Users and Ontologies.
 * TextQueryServlet
 * doGet : SEARCH
 * doPost : <not-supported.>
 * BulkRequestServlet
 * doGet : LIST-REQUESTS
 * doPost: RESPOND

''These are the atomic pieces of the implementation; I'll work to flesh out a description of each one, and link them back to the individual functions they satisify. --TWD''

Additional Implementation Details:
 * Embedded relational database (Java "Derby") for data storage.
 * Lucene index of PRO and Requests, wrapped in a custom query servlet.
 * Jetty web server usage

Required Libraries
These libraries are required for our implementation, and included with the source distribution.
 * org.json
 * Jetty 7
 * Apache Derby, an embedded relational database that is (normally) packaged as part of Jetty.
 * Lucene 2.9.0
 * Jena
 * Internal OBO Parsing code
 * Apache Commons FileUpload and I/O

Required for HTML Test interface:
 * jQuery
 * jQuery UI

Browser Interface
''The test server is a test server -- I've set it up only for debugging and demonstration purposes. Requests lodged with this broker may be periodically erased without warning, the server state may be reset, etc. Please don't use it for anything important or semi-permanent. It's currently loaded with a "working version" of PRO we received from Darren, and it's running on the dev. server at Science Commons. -- TWD''


 * Pending Requests
 * Query Interface
 * New Request Interface
 * Example Request View

/Notes