Annotator API and JSON

Annotator API

The Annotator endpoint will examine text input and return relevant classes. Currently, the annotator only returns direct annotations (hierarchy and mapping annotations are planned for a future release [as of May 2013]).

Endpoints

GET /annotator?text={input text}

example:
/annotator?text=Melanoma+is+a+malignant+tumor+of+melanocytes+which+are+found+predominantly+in+skin+but+also+in+the+bowel+and+the+eye.

Parameters

Filtering & query behavior

ontologies={ontology_id1,ontology_id2,ontology_id3}
max_level={0..N}

Response Formats

Notes

• ... indicates that similar items to the previous will continue in the list
• // indicates a comment (text after this should not appear in response)
• {value1|value2} indicates expected values:

Annotation JSON

[
    {
        "annotatedClass": {
            "@id": "http://purl.bioontology.org/ontology/HL7/C0796561",
            "@type": "http://www.w3.org/2002/07/owl#Class",
            "links": {
                "self": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561",
                "ontology": "http://stagedata.bioontology.org/ontologies/HL7",
                "children": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/children",
                "parents": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/parents",
                "descendants": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/descendants",
                "ancestors": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/ancestors",
                "tree": "http://stagedata.bioontology.org/ontologies/HL7/classes/http%3A%2F%2Fpurl.bioontology.org%2Fontology%2FHL7%2FC0796561/tree",
                "@context": {
                    "self": "http://www.w3.org/2002/07/owl#Class",
                    "ontology": "http://data.bioontology.org/metadata/Ontology",
                    "children": "http://www.w3.org/2002/07/owl#Class",
                    "parents": "http://www.w3.org/2002/07/owl#Class",
                    "descendants": "http://www.w3.org/2002/07/owl#Class",
                    "ancestors": "http://www.w3.org/2002/07/owl#Class",
                    "tree": "http://www.w3.org/2002/07/owl#Class"
                }
            },
            "@context": {
                "@vocab": "http://data.bioontology.org/metadata/"
            }
        },
        "hierarchy": [ ],
        "annotations": [
            {
                "from": 1,
                "to": 8,
                "matchType": "PREF"
            }
        ]
    },
    . . .
]

Annotator JSON Schema

JSON-schema for description and validation of REST JSON responses.

• http://tools.ietf.org/id/draft-zyp-json-schema-03.html
• http://tools.ietf.org/html/draft-zyp-json-schema-03

{
  "type": "array",
  "title": "annotations",
  "description": "An array of annotator objects.",
  "items": { "type": "object" }
}

{
    "type": "object",
    "title": "annotator",
    "description": "An annotator object.",
    "additionalProperties": false,
    "properties": {
        "annotatedClass": { "type": "object", "required": true },
        "hierarchy": { "type": "array", "required": true },
        "annotations": { "type": "array", "required": true }
    }
}

{
    "type": "object",
    "title": "annotatedClass",
    "description": "An annotator annotatedClass object.",
    "additionalProperties": false,
    "properties": {
        "@id": { "type": "string", "format": "uri", "required": true },
        "@type": { "type": "string", "format": "uri", "required": true },
        "links": { "type": "object", "required": true },
        "@context": { "type": "object", "required": true }
    }
}

{
    "type": "object",
    "title": "annotated class links",
    "description": "An annotated class links object.",
    "additionalProperties": false,
    "properties": {
        "self": { "type": "string", "format": "uri", "required": true },
        "ontology": { "type": "string", "format": "uri", "required": true },
        "children": { "type": "string", "format": "uri" },
        "parents": { "type": "string", "format": "uri" },
        "descendants": { "type": "string", "format": "uri" },
        "ancestors": { "type": "string", "format": "uri" },
        "tree": { "type": "string", "format": "uri" },
        "@context": { "type": "object" }
    }
}

{
    "type": "object",
    "title": "annotation list item",
    "description": "An annotator annotation list item.",
    "additionalProperties": false,
    "properties": {
        "from": { "type": "number", "required": true },
        "to": { "type": "number", "required": true },
        "matchType": { "type": "string", "required": true }
    }
}