NAV Navbar
shell python jQuery
  • Introduction
  • Authentication
  • Models
  • Decision
  • Batch
  • Enterprise
  • Enterprise Deployment
  • Schema

    • Introduction

    Welcome to the UP2TOM API. The UP2TOM API functionality has been developed to support the integration between third party applications and TOM models.

    The UP2TOM API is a REST API that provides programmatic access to TOM models. The UP2TOM API identifies users with authorization tokens. All endpoints are authenticated. All requests made to the UP2TOM API must be using SSL. All requests and responses make use of the JSON API specification (Content-Type: application/vnd.api+json).

    There are language examples for curl, Python and jQuery. You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

    Authentication

    To authenticate, use this code:

    # With curl, you can just pass the correct header with each request
curl "api_endpoint"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('api_endpoint', headers=headers)

    $.ajax({
  url: 'api_endpoint',
  type: 'REQUEST_METHOD',
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    Make sure to replace <key> with your API key.

    UP2TOM uses API keys to provide authentication and identification. An API key is linked to a collection of models. Please contact our support team to obtain an API key.

    UP2TOM expects the API key to be included in all requests using the header:

    Authorization: Token <key>

    For testing and experimentation, the API can be used with the demo key 9307bfd5fa011428ff198bb37547f979. In which case the following authorization header can be used:

    Authorization: Token 9307bfd5fa011428ff198bb37547f979

    Models

    GET Get all models

    curl "https://api.up2tom.com/v3/models"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/models', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/models'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns JSON structured like this:

    {
  "data": [
    {
      "id": "abcd1234abcd1234abcd1234",
      "type": "model",
      "attributes": {
        "name": "Demo",
        "description": "A demo model",
        "publish-date": "2017-01-12T01:25:22.335Z",
        "publisher": "User 1",
        "measurements": {},
        "metadata": {},
        "exclusions": {}
      }
    },
    {
      "id": "5678abcd5678abcd5678abcd5678",
      "type": "model",
      "attributes": {
        "name": "Demo 2",
        "description": "Another demo model",
        "publish-date": "2017-01-18T09:15:22.000Z",
        "publisher": "User 2",
        "measurements": {},
        "metadata": {},
        "exclusions": {}
      }
    },
    {
      "id": "9123abcd9123abcd9123abcd9123",
      "type": "model",
      "attributes": {
        "name": "Demo 3",
        "description": "The last demo model",
        "publish-date": "2017-01-18T13:55:11.000Z",
        "publisher": "User 3",
        "measurements": {},
        "metadata": {},
        "exclusions": {}
      }
    }
  ]
}

    This endpoint returns all models linked to the API key.

    HTTP Request

    GET https://api.up2tom.com/v3/models

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    405 Method not allowed (POST)
    503 Service is currently unavailable

    GET Get a specific model

    curl "https://api.up2tom.com/v3/models/<model>"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/models/<model>', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/models/<model>',
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns JSON structured like this:

    {
  "data": {
    "id": "abcd1234abcd1234abcd1234",
    "type": "model",
    "attributes": {
      "name": "Demo",
      "description": "A demo model",
      "measurements": {
        "levers": [{
            "index": 0,
            "drop": 0.25
        }, {
            "index": 1,
            "drop": 0.75
        }]
      },
      "metadata": {
        "prediction": {
          "_cls": "Nominal",
          "name": "outcome",
          "question": "Is the patient old?",
          "domain": {
            "_cls": "DomainC",
            "values": ["Yes", "No"]
          }
        },
        "attributes": [{
          "_cls": "Nominal",
          "name": "INPUTVAR1",
          "question": "Age?",
          "domain": {
            "_cls": "DomainR",
            "lower": 0,
            "upper": 80,
            "interval": 1
          }
        }, {
          "_cls": "Continous",
          "name": "INPUTVAR2",
          "question": "Gender?",
          "domain": {
            "_cls": "DomainC",
            "values": ["Male", "Female"]
          }
        }]
      },
      "exclusions": [{
        "_cls": "ValueEx",
        "antecedent": {
          "_cls": "LTEQ",
          "index": 0,
          "threshold": 20
        },
        "consequent": {
          "_cls": "EQ",
          "index": 1,
          "threshold": "Yes"
        }
      }, {
        "_cls": "BlatantEx",
        "antecedent": {
          "_cls": "LTEQ",
          "index": 0,
          "threshold": 10
        },
        "consequent": {
          "value": "No"
        }
      }]
    }
  }
}

    This endpoint retrieves a single model based on the model ID.

    HTTP Request

    GET https://api.up2tom.com/v3/models/<model>

    URL Parameters

    Parameter Description
    model The ID of the model specification to retrieve

    HTTP Responses

    Status Code Description
    200 Success
    400 Bad model ID
    401 Missing or bad API key
    403 No access to model with the specified ID.
    403 API Key is not in use or has been disabled
    405 Method not allowed (POST)
    503 Service is currently unavailable

    Decision

    POST Query the model

    curl -X POST -d "{ data }" "https://api.up2tom.com/v3/decision/<model>"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.post('https://api.up2tom.com/v3/decision/<model>', json=data, headers=headers)

    $.post({
  url: 'https://api.up2tom.com/v3/decision/<model>',
  headers: { 'Authorization': 'Token <key>' },
  data: JSON.stringify(data),
  contentType: 'application/vnd.api+json'
});

    The above command receives JSON structured like this:

    {
  "data": {
    "type": "scenario",
    "attributes": {
      "input": {
        "INPUTVAR1": 1.0,
        "INPUTVAR2": "Yes",
        "INPUTVAR3": "Green",
        "INPUTVAR4": 4.0
      }
    }
  }
}

    OR

    {
  "data": {
    "type": "scenario",
    "attributes": {
      "input": [1.0, "Yes", "Green", 4.0]
      }
  }
}

    OR

    {
  "data": {
    "type": "scenario",
    "attributes": {
      "input": {
        "Cars owned?": 1.0,
        "All paid off?": "Yes",
        "Favorite color?": "Green",
        "Cars owned?": 4.0
      }
    }
  }
}

    and returns JSON structured like this:

    {
    "data": {
        "type": "scenario",
        "attributes": {
            "timestamp": "2017-08-03T08:06:50.777Z",
            "input": {
              "INPUTVAR1": 1.0,
              "INPUTVAR2": "Yes",
              "INPUTVAR3": "Green",
              "INPUTVAR4": 4.0
            },
            "decision": "Yes",
            "meets-confidence": false
        }
    }
}

    This endpoint returns a decision using a specific model and an input scenario.

    HTTP Request

    POST https://api.up2tom.com/v3/decision/<model>

    URL Parameters

    Parameter Description
    model The ID of the model

    Body Parameters

    See the code sample to the right.

    HTTP Responses

    Status Code Description
    200 Success
    400 Bad model ID
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    403 No access to model with the specified ID
    422 Invalid input. See error detail
    405 Method not allowed (GET)
    503 Service is currently unavailable

    Batch

    In addition to single-scenario decisions, the API provides the ability to make batch decisions. The Batch endpoint can be used to upload a pipe-delimited CSV file, where each row corresponds to one scenario. The uploaded file is placed in queue and processed on a first-come-first-served basis. During batch processing, an extra column is added to each row, indicating the decision of the scenario. Finally, when processing is complete, the file can be downloaded.

    GET List batch files and running jobs

    curl "https://api.up2tom.com/v3/batch/<model>"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/batch/<model>', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/batch/<model>',
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns JSON structured like this:

    {
  "data": {
    "files": [
      {
        "id": "59883bb272240648161cb87f",
        "filename": "My old batch file.csv",
        "size": 9178,
        "timestamp": "2017-08-07T07:43:22.485Z",
        "errors": [
          {
            "message": "Number of questions given does not match with number of questions in the specification.",
            "value": "10 vs 9."
          }
        ]
      }
    ],
    "jobs": [
      {
        "id": "59883bb272240648161cb87f",
        "filename": "My batch file.csv",
        "uploaded": "2017-08-08T06:43:03.762Z",
        "size": 9178,
        "progress": 0.4,
        "delimiter": ","
      }
    ]
  }
}

    This endpoint provides a query of the current state of Batch for the specified model. It returns both a list of active jobs, as well as a list of any previously processed batch files.

    HTTP Request

    GET https://api.up2tom.com/v3/batch/<model>

    URL Parameters

    Parameter Description
    model The ID of the model

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    503 Service is currently unavailable

    POST Upload batch file

    curl -X POST "https://api.up2tom.com/v3/batch/<model>"
  -H "Authorization: Token <key>"
  -H "Content-Type: multipart/form-data"
  -F "file=@/path/to/file"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'multipart/form-data'
}
files = { 'file': ('some_file.csv', open('/path/to/file/', 'rb') }
r = requests.post('https://api.up2tom.com/v3/batch/<model>', files=files, headers=headers)

    var data = new FormData();
data.append('file', $('input[name=file]'));
data.append('delimiter', ',');

$.post({
  url: 'https://api.up2tom.com/v3/batch/<model>',
  headers: { 'Authorization': 'Token <key>' },
  data: data,
  contentType: false
});

    The above command returns JSON structured like this:

    {
  "data": {
    "jobs": [
      {
        "id": "59883bb272240648161cb87f",
        "filename": "Some file.csv",
        "uploaded": "2017-08-08T06:43:03.762Z",
        "size": 9178,
        "progress": 0,
        "delimiter": ","
      }
    ]
  }
}

    This endpoint allows the client to upload a pipe-delimited CSV file that will be batch processed. Upon successful upload, it returns a list of active jobs for the specified model.

    HTTP Request

    POST https://api.up2tom.com/v3/batch/<model>

    URL Parameters

    Parameter Description
    model The ID of the model

    Form Fields

    Field Description
    file The file to process
    delimiter The delimiter character used in the file (default ,)

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    422 Missing file, file too large, or invalid delimiter
    503 Service is currently unavailable

    GET Retrieve processed batch file

    curl "https://api.up2tom.com/v3/batch/<model>/<batch-file>"
  -H "Authorization: Token <key>"

    import requests

headers = {
  'Authorization': 'Token <key>'
}
r = requests.get('https://api.up2tom.com/v3/batch/<model>/<batch-file>', headers=headers)

    $.get({
  headers: { 'Authorization': 'Token <key>' },
  url: 'https://api.up2tom.com/v3/batch/<model>/<batch-file>',
});

    The above command returns the processed file with the text/csv; charset=UTF-8 Content-Type.

    This endpoint allows the client to download a processed batch file.

    HTTP Request

    GET https://api.up2tom.com/v3/batch/<model>/<batch-file>

    URL Parameters

    Parameter Description
    model The ID of the model
    batch-file The ID of the batch file

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    404 Batch file does not exist
    503 Service is currently unavailable

    DEL Delete batch file

    curl -X DELETE "https://api.up2tom.com/v3/batch/<model>/<batch-file>"
  -H "Authorization: Token <key>"

    import requests

headers = {
  'Authorization': 'Token <key>'
}
r = requests.delete('https://api.up2tom.com/v3/batch/<model>/<batch-file>', headers=headers)

    $.ajax({
  type: 'DELETE',
  headers: { 'Authorization': 'Token <key>' },
  url: 'https://api.up2tom.com/v3/batch/<model>/<batch-file>',
});

    A response of 204 (No Content) indicates a successful delete.

    This endpoint allows the client to delete a processed batch file.

    HTTP Request

    DEL https://api.up2tom.com/v3/batch/<model>/<batch-file>

    URL Parameters

    Parameter Description
    model The ID of the model
    batch-file The ID of the batch file

    HTTP Responses

    Status Code Description
    204 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    404 Batch file does not exist
    503 Service is currently unavailable

    Enterprise

    The /v3/enterprise/ endpoints facilitate the process of packaging and downloading model JAR files for use with the Enterprise API.

    POST Package model

    curl \
  -X POST \
  -H "Authorization: Token <key>" \
  -H "Content-Type: application/vnd.api+json" \
  -o "<model name>.jar" \
  "https://api.up2tom.com/v3/enterprise/package/<model>"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.post('https://api.up2tom.com/v3/enterprise/package/<model>', headers=headers)

    $.post({
  url: 'https://api.up2tom.com/v3/enterprise/package/<model>'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    the above command returns the package as binary data.

    Build a package containing a single model.

    HTTP Request

    POST https://api.up2tom.com/v3/enterprise/package/<model>

    URL Parameters

    Parameter Description
    model The ID of the model

    HTTP Responses

    Status Code Description
    200 Success
    202 Successful request but package was not built in time
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    405 Method not allowed (GET)
    503 Service is currently unavailable

    POST Package all models

    curl \
  -X POST \
  -H "Authorization: Token <key>" \
  -H "Content-Type: application/vnd.api+json" \
  -o "models.jar" \
  "https://api.up2tom.com/v3/enterprise/package/all"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/enterprise/package/all', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/enterprise/package/all'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    the above command returns the package as binary data.

    Build a package containing all models related to the API key.

    HTTP Request

    POST https://api.up2tom.com/v3/enterprise/package/all

    HTTP Responses

    Status Code Description
    200 Success
    202 Successful request but package was not built in time
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    405 Method not allowed (GET)
    503 Service is currently unavailable

    GET View available packages

    curl "https://api.up2tom.com/v3/enterprise/packages"
  -H "Authorization: Token <key>"
  -H "Content-Type: application/vnd.api+json"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/enterprise/packages', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/enterprise/packages'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns JSON structured like this:

    {
  "data": [
    {
      "type": "jar",
      "id": "5a7025eb7224062ca0f96678",
      "attributes": {
        "name": "models.jar",
        "size": 26255,
        "package-date": "2018-01-30T07:59:39.495Z",
        "md5": "c7a5a2dd01dc4e781287e05377e7cd72"
      }
    },
    {
      "type": "jar",
      "id": "5a741a7f7224061be1fc909b",
      "attributes": {
        "name": "models.jar",
        "size": 414369,
        "package-date": "2018-02-02T07:59:59.284Z",
        "md5": "e0703c7351d6b72ad1223985c573753f"
      }
    }
  ]
}

    This endpoint returns all model packages that have already been built.

    HTTP Request

    GET https://api.up2tom.com/v3/enterprise/packages

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    405 Method not allowed (POST)
    503 Service is currently unavailable

    GET Package

    curl "https://api.up2tom.com/v3/enterprise/packages/<package>" \
  -H "Authorization: Token <key>" \
  -H "Content-Type: application/vnd.api+json" \
  -o "models.jar"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/enterprise/packages/<package>', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/enterprise/packages/<package>'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns binary data

    This endpoint returns the package with the specified ID.

    HTTP Request

    GET https://api.up2tom.com/v3/enterprise/packages/<package>

    URL Parameters

    Parameter Description
    package The ID of the package to download

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    404 Package does not exist
    405 Method not allowed (POST)
    503 Service is currently unavailable

    GET Latest package

    curl "https://api.up2tom.com/v3/enterprise/packages/latest" \
  -H "Authorization: Token <key>" \
  -H "Content-Type: application/vnd.api+json" \
  -o "models.jar"

    import requests

headers = {
  'Authorization': 'Token <key>',
  'Content-Type': 'application/vnd.api+json'
}
r = requests.get('https://api.up2tom.com/v3/enterprise/packages/latest', headers=headers)

    $.get({
  url: 'https://api.up2tom.com/v3/enterprise/packages/latest'
  headers: { 'Authorization': 'Token <key>' },
  contentType: 'application/vnd.api+json'
});

    The above command returns binary data

    This endpoint returns the latest package that has been built.

    HTTP Request

    GET https://api.up2tom.com/v3/enterprise/packages/latest

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    405 Method not allowed (POST)
    503 Service is currently unavailable

    DEL Delete package

    curl -X DELETE "https://api.up2tom.com/v3/enterprise/packages/<package>"
  -H "Authorization: Token <key>"

    import requests

headers = {
  'Authorization': 'Token <key>'
}
r = requests.delete('https://api.up2tom.com/v3/enterprise/packages/<package>', headers=headers)

    $.ajax({
  type: 'DELETE',
  headers: { 'Authorization': 'Token <key>' },
  url: 'https://api.up2tom.com/v3/enterprise/packages/<package>',
});

    A response of 204 (No Content) indicates a successful delete.

    This endpoint allows the client to delete a package.

    HTTP Request

    DEL https://api.up2tom.com/v3/enterprise/packages/<package>

    URL Parameters

    Parameter Description
    package The ID of the package to be deleted

    HTTP Responses

    Status Code Description
    204 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    404 Package does not exist
    503 Service is currently unavailable

    DEL Delete all packages

    curl -X DELETE "https://api.up2tom.com/v3/enterprise/packages/all"
  -H "Authorization: Token <key>"

    import requests

headers = {
  'Authorization': 'Token <key>'
}
r = requests.delete('https://api.up2tom.com/v3/enterprise/packages/all', headers=headers)

    $.ajax({
  type: 'DELETE',
  headers: { 'Authorization': 'Token <key>' },
  url: 'https://api.up2tom.com/v3/enterprise/packages/all',
});

    A response of 204 (No Content) indicates a successful delete.

    This endpoint allows the client to delete ALL packages.

    HTTP Request

    DEL https://api.up2tom.com/v3/enterprise/packages/all

    HTTP Responses

    Status Code Description
    204 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    503 Service is currently unavailable

    POST Convert package

    curl \
  -X POST \
  -F "file=@models.jar" \
  -H "Authorization: Token <key>" \
  "https://api.up2tom.com/v3/enterprise/package/convert" \
  -o "models-converted.jar"

    This endpoint allows the client to downgrade a version 0.1.3 package.

    HTTP Request

    POST https://api.up2tom.com/v3/enterprise/package/convert

    HTTP Responses

    Status Code Description
    200 Success
    401 Missing or bad API key
    403 API Key is not in use or has been disabled
    503 Service is currently unavailable

    Enterprise Deployment

    The enterprise API (0.1.4) is an offline, self-hosted JAVA rest service that provides the same functionality as the UP2TOM API. The enterprise API comprises two parts:

    1. The API service file (JAR)
    2. Model files (JARs)

    Minimum System Requirements

    The API is designed to be lightweight. There are no database or external network connections during operation. Depending on model complexity, the API can reliably handle ≈200 requests per second.

    The minimum system requirements are:

    API Contents

    • up2tom_enterprise_api.zip
      • up2tom-enterprise-api_version.jar(api jar)
      • start_up2tom_api.sh  (unix start script)
      • start_up2tom_api.bat (windows start script)
      • logback.xml          (log configuration)
      • Dockerfile           (docker build file)
      • models               (models directory)
        • model1.jar
        • model2.jar
        • model3.jar
        • ...

    Logging

    The enterprise API has a configurable logging system based on logback.

    Logging is configured using the logback.xml file.

    Please refer to the following link for possible logging configurations:

    Deployment

    The enterprise API can be run in the foreground using the startup scripts provided. This is useful for testing. However, for production, the API should be run as a background process. We recommend the following approaches for deployment:

    Docker

    # build docker image
docker build -t up2tom-enterprise-api .

# create shared volume for batch file processing
docker volume create TomFilesVolume

# run up2tom-enterpise-api image
docker run -d -p $PORT:8080 \
 -v /path/to/models/directory:/api/models \
 -v TomFilesVolume:/api/files \
 up2tom-enterprise-api

    Where $PORT is the port number on the host machine where you want the API to serve requests.

    Using Docker is the fastest way to get up and running. A sample Dockerfile is provided along with the enterprise API. To get started, ensure that you have Docker installed and then enter the commands on the right.

    Note that the Enterprise API creates a local database and stores files when doing batch processing. These files need to be shared across containers when scaling up. This can be accomplished using a shared volume.

    Similarly, model JARs can be specific to each container however it is more likely that you will share model JARs across all containers using a shared volume/mount.

    Schema

    The UP2TOM API exposes several different data structures that provide information about the model. In order to gain a better understanding, each component is described here from the top down.

    Component Description
    Model A container for all the properties of the model
    Metadata A description of the input variables and model outcomes
    Attribute A specification for an individual input variable or outcome
    Domain Range of possible values for an input variable or outcome
    Exclusion Rules Rules that reduce the possible set of input or rules that enforce an automatic outcome
    Relation A relationship restriction between two variables or between a variable and a value
    Result An outcome
    Measurements Technical information about the model

    Model

    Model Description

    {
  "title": "Model",
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "type": "string",
        "id": "string",
        "attributes": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "description": { "type": "string" },
            "publish-date": { "type": "string" },
            "publisher": { "type": "string" },
            "measurements": { "$ref": "/Measurements" },
            "metadata": { "$ref": "/Metadata" },
            "exclusions": { "$ref": "/Exclusions" }
          },
          "required": [
            "name",
            "description",
            "publish-date",
            "publisher",
            "metadata",
            "exclusions",
            "measurements"
          ]
        },
      },
      "required": ["type", "id", "attributes"]
    }
  },
  "required": ["data"]
}

    The model contains all information about the model, including name, description, publisher, as well as information about the specification and even technical information such as model accuracy.

    Model Description

    The model description contains the following properties:

    Property Description
    id A unique 24 character hex string
    name The name of the model
    description A description of the model
    publisher The username of the model creator
    publish-date The date the model was last updated
    metadata Metadata describing the input variables and outcomes
    exclusions Exclusions rules
    measurements Technical information about the model

    Metadata

    {
  "title": "Metadata",
  "type": "object",
  "properties": {
    "attributes": {
      "type": "array",
      "items": { "$ref": "#/definitions/Attribute" }
    },
    "prediction": { "$ref": "#/definitions/Attribute" }
  }
}

    Metadata specifies the input variables and outcomes for the model. Each model has multiple input variables and a decision variable which contains several possible outcomes.

    The Metadata object contains the following properties:

    Property Description
    attributes A list of Attributes describing the input variables
    prediction A single Attribute describing the model outcomes

    Attribute

    {
  "title": "Attribute",
  "type": "object",
  "properties": {
    "type": "string",
    "name": "string",
    "question": "string",
    "domain": { "$ref": "#/definitions/Domain" }
  }
}

    An attribute is a description of a single input or decision variable. Each attribute in a model has a unique name and a question. Additionally, each attribute is constrained by a domain.

    The Attribute object contains the following properties:

    Property Description
    type The type of attribute, either Nominal or Continuous
    name The name of the attribute, e.g. INPUTVAR1
    question The question that is presented during simulation
    domain The domain of the attribute

    Attributes belong to one of three different types, each describing the type of input variable.

    Continuous

    An attribute for a numeric input.

    Nominal

    An attribute for a collection of possible text values.

    Ordinal

    An attribute for a collection of possible text values where the order of the values is important, e.g. low, medium, high.

    Domain

    The Domain object is an important component that defines the types of the input and decision variables. The domain is used during the simulation process to ensure that only feasible scenarios are generated. Additionally, the domain is used during the decision process by validating each input scenario. E.g. the lower and upper bounds for each continuous variable are checked when making a decision.

    Continuous Domain

    Continuous Domain

    {
  "title": "Continuous Domain",
  "type": "object",
  "properties": {
    "type": "string",
    "lower": "number",
    "upper": "number",
    "interval": "number",
    "discrete": "boolean"
  }
}

    The Continuous Domain object describes a numeric variable and contains the following properties:

    Property Description
    type The type of domain, in this case DomainR
    lower The lower bound (inclusive) of the variable. An input must be greater than or equal to this
    upper The upper bound (inclusive) of the variable. An input must be less than or equal to this
    interval The step of the variable used in simulation. This value can be used to restrict possible inputs but is not validated during the decision process
    discrete Whether or not this variable describes a whole number

    Categorical Domain

    Categorical Domain

    {
  "title": "Categorical Domain",
  "type": "object",
  "properties": {
    "type": "string",
    "values": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

    The Categorical Domain object describes a variable with multiple text outcomes and contains the following properties:

    Property Description
    type The type of domain, in this case DomainC
    values A list of possible string values for this variable

    Relation

    {
  "title": "Relation",
  "type": "object",
  "properties": {
    "type": "string",
    "index": "integer",
    "threshold": "number"
  }
}

    A relation describes a relationship between two variables or a relationship between a variable and a value. The different types of Relations correspond to different operators:

    Type Operator
    LTEQ ≤
    GT >
    EQ =
    NEQ ≠

    The Relation object contains the following properties:

    Property Description
    type The type of Relation. Possible types of relations include LTEQ, GT, EQ and NEQ
    index An integer index of an Attribute in the Metadata
    threshold A value to be compared against, either a number or text depending on the relation type

    Result

    {
  "title": "Class Result",
  "type": "object",
  "properties": {
    "type": "string",
    "value": "string"
  }
}

    UP2TOM uses results to store the outcome of a decision. Currently, only text outcomes are allowed. These results are termed Class Results.

    The Result object contains the following properties:

    Property Description
    type The type of result, in this case ClassRes
    value A single text value representing a model outcome

    Exclusion Rules

    Exclusion rules are powerful components used to either restrict the feasibility of input scenarios or as a way to short-circuit the decision making process by immediately returning a user-defined outcome. Exclusion rules make use of Relations to describe the relationships between variables or between a variable and an outcome.

    Value Exclusion

    Value Exclusion

    {
  "title": "Value Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "antecedent": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/Relation"
      }
    },
    "consequent": {
      "type": "array",
      "items": { "$ref": "#/definitions/Relation" }
    }
  }
}

    A value exclusion describes an IF -> THEN rule. The Relations in the antecedent form a compound IF A AND B AND C statement. The Relations in the consequent form a compound THEN X AND Y AND Z statement. In other words, an input scenario is satisfied by a value exclusion if all of the relations in the antecedent and all of the relations in the consequent are satisfied.

    The Value Exclusion object contains the following properties:

    Property Description
    type The type of exclusion rule, in this case ValueEx
    antecedent A list of Relations that form the IF statement
    consequent A list of Relations that form the THEN statement

    Relationship Exclusion

    Relationship Exclusion

    {
  "title": "Relationship Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "relation": { "$ref": "#/definitions/Relation" }
  }
}

    A relationship exclusion describes a MUST BE rule. The type of the Relation specifies the operator of the rule, i.e. ≤ or>. The index of the Relation describes the Attribute on the left side of the operator. The threshold is used as an index to describe the Attribute on the right side of the operator. This builds a rule in the form A MUST BE ≤ or A MUST BE > B.

    The Relationship Exclusion object contains the following properties:

    Property Description
    type The type of exclusion rule, in this case RelationshipEx
    relation A Relation between two variables

    Blatant Exclusion

    Blatant Exclusion

    {
  "title": "Blatant Exclusion",
  "type": "object",
  "properties": {
    "type": "string",
    "antecedent": { "$ref": "#/definitions/Relation" },
    "consequent": { "$ref": "#/definitions/Result" }
  }
}

    A blatant exclusion describes an IF A -> THEN RESULT IS B rule. It is used to produce an automatic decision before querying the model. The antecedent describes a single IF rule. If the antecedent is satisfied, the decision is set to the value stored in the result.

    A Blatant Exclusion contains the following properties:

    Property Description
    type The type of exclusion rule, in this case BlatantEx
    antecedent A Relation for a single IF rule
    consequent A Result for the THEN rule

    Measurements

    {
  "title": "Measurements",
  "type": "object",
  "properties": {
    "levers": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": "integer",
          "drop": "number"
        }
      }
    }
  }
}

    The measurements object contains the levers (variable importance) for the model. Each lever is described using an index (of the variable in the Metadata), and a drop in percentage. The drop in percentage is an estimate of how important a variable is with higher values indicating more importance and lower values indicating less importance.

    The Measurement object contains the following properties:

    Property Description
    levers A list of levers describing the importance of each input variable

    Job

    {
  "title": "Job",
  "type": "object",
  "properties": {
      "filename": "string",
      "uploaded": "date",
      "size": "number",
      "progress": "number"
  }
}

    The job object contains information about a running batch job. Jobs remain in a queue and are processed one-by-one in the order they are created.

    The Job object contains the following properties:

    Property Description
    filename The name of the uploaded batch file
    uploaded Timestamp indicating when the file was uploaded
    size The size of the file in bytes
    progress The current progress of the job (0.0 to 1.0)

    Batch File

    {
  "title": "Batch File",
  "type": "object",
  "properties": {
    "id": "string",
    "filename": "string",
    "size": "number",
    "timestamp": "date",
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "message": "string",
          "value": "string"
        }
      }
    }
  }
}

    The batch file object contains information about a processed batch file.

    The Batch File object contains the following properties:

    Property Description
    id A unique 24 character hex string (used to retrieve or delete the file)
    filename The name of the uploaded batch file
    timestamp Timestamp indicating when the file was processed
    size The size of the file in bytes
    errors A list of possible errors that were encountered while processing the file
    shell python jQuery