Open Tree API datatypes

The APIs use a number of standardized dictionaries to group fields in the output parameters. This doc describes these custom datatypes.

##taxon-blob The taxon-blob groups fields about a taxon. It is used in the tree-of-life and taxonomy methods. A taxon blob has the following fields (a field is absent if no value, not returned as empty string):

ott_id : (int) the OTT ID name : (string) taxon-name-string rank : (string) rank-string unique_name : (string) the string that uniquely identifies the taxon in OTT tax_sources : (list of strings) an ordered list of identifiers for taxonomic sources, such as other taxonomies, that define taxa judged equivalent to this taxon. Each string in the list has a CURIEorIRI syntax, so this field might hold [“ncbi:9242”, “h2007:”, “http://dx.doi.org/10.9779/azhjj0”], for example.

##node-blob The node-blob groups fields that describe a node in the synthetic tree. node-blob has a node_id field giving the id of a synthetic tree node, a taxon field giving a taxon-blob for the corresponding taxon if there is one (taxon is absent if the node doesn’t correspond to a taxon), num_tips giving the number of tips in the synthetic tree tipward of this node, and up to five support/conflict fields whose values are support-blobs.

`node_id` : (string) the ID of the synthetic tree node, e.g. “mrcaott3504ott396446”
`taxon` : { }  a [taxon-blob](#taxon-blob); present only if the node is a taxon
`num_tips` : (int) the number of tips in the synthetic tree reachable tipward from the specified node; zero if the node is itself a synthetic tree tip.
`supported_by` : [support-blob](#support-blob)  e.g. {
      "pg_1944@tree3959" : "node741000"
}
`conflicts_with` : { … }  [support-blob](#support-blob)
`resolves` :  { … }  [support-blob](#support-blob)
`partial_path_of` : { … }  [support-blob](#support-blob)
`terminal` : { … }  [support-blob](#support-blob)

For the five support/conflict properties, the support-blob values are always nonempty. If there are no conflicting (resolving, etc.) source nodes, then the blob has no conflicts_with (resolves, etc.) field rather than a field whose value is an empty dictionary {}.

Whenever a node-blob is returned by a method, there is also (elsewhere in the method response) a source-id-map (see below) so that the source tree ids in the support/conflict properties can be interpreted.

##support-blob The support-blob describes the source tree nodes that correspond to nodes in the synthetic tree. A support-blob is a dictionary keyed by source tree id (sourceid-string). The value is either a single nodeid-string, or a list of nodeid-strings, depending on whether the support/conflict relation involved is one-to-one or one-to-many. supported_by, resolves, and terminal are one-to-one; partial_path_of and conflicts_with are one-to-many. Example:

    "supported_by" : {
      "pg_1944@tree3959" : "node741000",
      "pg_2539@tree6294" : "node1094822"
    }
    {
      "pg_1944@tree3959" : ["node741000", "node1094822"],
     ...
    }

The sourceid-string is a short identifier for an source tree. The full description of a source tree consists of a study ID, a tree ID, and the SHA that identifies the version of the study. Because passing around this triple of information to refer to a study tree is cumbersome, many methods use a unique string to refer to a tree. These strings are given pseudo-type sourceid-string. Client code should treat this string as an opaque key and look up the full information in the the source-id-map, which provides the triple of information that fully describes each source tree.

##source-id-map A source-id-map object is a dictionary with sourceid-strings as keys. The value associated with each key is a blob with three properties: git_sha, tree_id, study_id. The values for each of these properties are strings. Example:

"source_id_map" : {
      "pg_2573@tree5959" : {
        "git_sha" : "c6ce2f9067e9c74ca7b1f770623bde9b6de8bd1f",
        "tree_id" : "tree5959",
        "study_id" : "pg_2573"
      }
    }

##extended-taxon-blob Certain taxonomy-related methods return taxon blobs that contain the additional taxon properties flags, synonyms, and is_suppressed.

ott_id : (int) the OTT ID name : (string) taxon-name-string rank : (string) rank-string unique_name : (string) the string that uniquely identifies the taxon in OTT tax_sources : (list of strings) an ordered list of identifiers for taxonomic sources, such as other taxonomies, that define taxa judged equivalent to this taxon. Each string in the list has a CURIEorIRI syntax, so this field might hold [“ncbi:9242”, “h2007:”, “http://dx.doi.org/10.9779/azhjj0”], for example. flags : (list of strings) see the taxonomy documentation for more info synonyms : (list of strings) the synonyms for this taxon is_suppressed : (boolean) whether the