JSON serialization for all OpenTox API resources

[vedina]

A proposal for additional supported representation with MIME types

JSON: application/json
JSONP:  application/x-javascript

As JavaScript/JSON are the primary tools used in web development, supporting JSON serialisation will simplify web UI development. There will be also performance improvements over using RDF serialisations.

Examples and documentation as per AMBIT implementation at https://github.com/ideaconsult/examples-ambit/tree/master/ambit-json-docs

[egonw]

Should we standardize on the structure of the data within the JSON? Otherwise, different resources may output the same calculations results in a different JSON hierarchy?

[vedina]

Sure. The link to AMBIT implementation contains JSON examples for most of OpenTox resources, and these are fairly close to the RDF data model.

Dataset

Metadata

{
    "dataset": [
        {
            "URI": "http://host:port/app/dataset/1",
            "type": "Dataset",
            "title": "The dataset name",
            "stars": 5,
            "rightsHolder": "XXX",
            "seeAlso": "http://ambit.sourceforge.net",
            "rights": {
                "URI": "http://ambit.sf.net/resolver/rights/",
                "type": "rights"
            }
        }
    ]
}

Data entries

{
    "dataEntry": [
        {
            "compound": {
                "URI": "http://apps.ideaconsult.net:8080/ambit2/compound/{id}/conformer/{id}"
            },
            "values": {
                "key1": "value1",
                "key2": 3.14
            }
        },
        {
            "compound": {
                "URI": "http://host:port/ambit2/compound/{id}/conformer/{id}"
            },
            "values": {
                "key1": "value3",
                "key3": "value4"
            }
        }
    ],
    "feature": {
        "key1": {
            "type": "Feature",
            "title": "Title1",
            "units": "",
            "isNominal": false,
            "isNumeric": false,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": false,
            "creator": "URI",
            "order": 1,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Dataset"
            }
        },
        "key2": {
            "type": "Feature",
            "title": "Title2",
            "units": "",
            "isNominal": false,
            "isNumeric": true,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": false,
            "creator": "URI",
            "order": 3,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Algorithm"
            }
        },
        "key3": {
            "type": "Feature",
            "title": "Title 3",
            "units": "",
            "isNominal": false,
            "isNumeric": false,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": true,
            "creator": "URI",
            "order": 2,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Model"
            }
        }
    }
}

Compound (same as Dataset). The "mol" entry is optional.

{
    "query": {
        "summary": "idcompound=1"
    },
    "dataEntry": [
        {
            "compound": {
                "URI": "http://apps.ideaconsult.net:8080/bioclipse/compound/1/conformer/1",
                "structype": "D2noH",
                "mol": "C1=CC=CC=C1\r\nJME 2006.05 Thu Apr 04 18:12:10 EEST 2013\r\n\r\n  6  6  0  0  0  0  0  0  0  0999 V2000\r\n    2.4249    0.7000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n    2.4249    2.1000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n    1.2124    2.8000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n    0.0000    2.1000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n    0.0000    0.7000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n    1.2124    0.0000    0.0000 C   0  0  0  0  0  0  0  0  0  0  0  0\r\n  1  2  1  0  0  0  0\r\n  2  3  2  0  0  0  0\r\n  3  4  1  0  0  0  0\r\n  4  5  2  0  0  0  0\r\n  5  6  1  0  0  0  0\r\n  6  1  2  0  0  0  0\r\nM  END",
                "metric": null,
                "name": "",
                "cas": "",
                "einecs": "",
                "inchikey": "UHOVQNZJYSORNB-UHFFFAOYSA-N",
                "inchi": "InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H",
                "formula": "C6"
            },
            "values": {},
            "facets": []
        }
    ],
    "model_uri": null,
    "feature": {}
}

Feature

{
    "feature": {
        "key1": {
            "type": "Feature",
            "title": "Title1",
            "units": "",
            "isNominal": false,
            "isNumeric": false,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": false,
            "creator": "URI",
            "order": 1,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Dataset"
            }
        },
        "key2": {
            "type": "Feature",
            "title": "Title2",
            "units": "",
            "isNominal": false,
            "isNumeric": true,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": false,
            "creator": "URI",
            "order": 3,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Algorithm"
            }
        },
        "key3": {
            "type": "Feature",
            "title": "Title 3",
            "units": "",
            "isNominal": false,
            "isNumeric": false,
            "sameAs": "ONTOLOGY_ENTRY",
            "isModelPredictionFeature": true,
            "creator": "URI",
            "order": 2,
            "source": {
                "URI": "URI of a dataset, algorithm, or a model",
                "type": "Model"
            }
        }
    }
}

Algorithm

{
    "algorithm": [
        {
            "uri": "http://host:port/ambit2/algorithm/SimpleKMeans",
            "id": "SimpleKMeans",
            "name": "Clustering: k-means",
            "type": [
                "http://www.opentox.org/algorithmTypes.owl#Clustering",
                "http://www.opentox.org/algorithmTypes.owl#SingleTarget",
                "http://www.opentox.org/algorithmTypes.owl#LazyLearning",
                "http://www.opentox.org/algorithmTypes.owl#UnSupervised"
            ]
        },
        {
            "uri": "http://host:port:8080/ambit2/algorithm/J48",
            "id": "J48",
            "name": "Classification: Decision tree J48",
            "type": [
                "http://www.opentox.org/algorithmTypes.owl#Classification",
                "http://www.opentox.org/algorithmTypes.owl#SingleTarget",
                "http://www.opentox.org/algorithmTypes.owl#EagerLearning",
                "http://www.opentox.org/algorithmTypes.owl#Supervised"
            ]
        },
        {
            "uri": "http://host:port/ambit2/algorithm/LR",
            "id": "LR",
            "name": "Regression: Linear regression",
            "type": [
                "http://www.opentox.org/algorithmTypes.owl#Regression",
                "http://www.opentox.org/algorithmTypes.owl#SingleTarget",
                "http://www.opentox.org/algorithmTypes.owl#EagerLearning",
                "http://www.opentox.org/algorithmTypes.owl#Supervised"
            ]
        },
        {
            "uri": "http://host:port/ambit2/algorithm/org.openscience.cdk.qsar.descriptors.molecular.XLogPDescriptor",
            "id": "org.openscience.cdk.qsar.descriptors.molecular.XLogPDescriptor",
            "name": "XLogP",
            "endpoint": "http://www.opentox.org/echaEndpoints.owl#Octanol-water_partition_coefficient_Kow",
            "implementationOf": "http://www.blueobelisk.org/ontologies/chemoinformatics-algorithms/#xlogP",
            "type": [
                "http://www.opentox.org/algorithmTypes.owl#DescriptorCalculation"
            ]
        },
        {
            "uri": "http://host:port/ambit2/algorithm/toxtreecramer",
            "id": "toxtreecramer",
            "name": "ToxTree: Cramer rules",
            "endpoint": "http://www.opentox.org/echaEndpoints.owl#HumanHealthEffects",
            "implementationOf": "http://ambit.sourceforge.net/descriptors.owl#toxtreecramer",
            "type": [
                "http://www.opentox.org/algorithmTypes.owl#Rules"
            ]
        }
    ]
}

Model and Task

{
    "model": [
        {
            "URI": "http://host:port/ambit2/model/{mid}",
            "id": 2,
            "title": "ToxTree: Cramer rules",
            "stars": 9,
            "algorithm": {
                "URI": "http://host:port/ambit2/algorithm/{aid}"
            },
            "trainingDataset": "http://host:port/ambit2/dataset/{did}",
            "independent": "http://host:port/ambit2/model/2/independent",
            "dependent": "http://host:port/ambit2/model/{mid}/dependent",
            "predicted": "http://host:port/ambit2/model/{mid}/predicted"
        }
    ]
}

Task

{"task": [
{
        "uri":"http://host:port/ambit2/task/{id}",
        "id": "7aadd2a5-06de-4ae2-851e-3e13ca6811d9",
        "name": "The model name",
        "status": "Running",
        "started": 1371742727965,
        "result": "http://host:port/ambit2/task/7aadd2a5-06de-4ae2-851e-3e13ca6811d9",
}
]

Suggestions for improvements welcome.

[egonw]

How do you propose to formalize this hierarchy?

[vedina]

Copied JSON examples from the current implementation.

There is usually an array of entries, which is convenient to show in jQuery DataTables. JSON is not necessary a hierarchy with a single root - it is rather a nested hashtable. For example the dataset representation has more than one top level hash keys - i.e. dataEntry and feature.