1. OCCAM Avatar OCCAM
  2. Occam System
  3. occam-web

Wiki

Clone wiki

occam-web / Beginners-Guide / 2.Adding-a-Configuration-Schema

View History

PREVIOUS: Creating a simple OCCAM object

Adding the Configuration Schema

The configuration schema, defines the options that are available to the object. These schemas are written in JSON and follow this layout: 

{
    <variable name>:{
        "type":<variable type>,
        "default":<default value>,
        "label":<variable label>,
        "description":<variable description>,    
        "validation":<variable validation> (if <variable type> == "int")
    },
    <variable name>:...
}

OCCAM currently supports four different configuration types: 1. int 2. string 3. list 4. boolean

To make those options available in our example, we need both a file containing the schema, and to declare it in our object description file (object.json).

Describing the configuration schema

Create a file named config_schema.json: 

$ touch ~/occam_workspace/simulator-ExampleSim/config_schema.json
This file defines the configuration schema, and in our case we will have four variables. The first is an int value, which we want to be a power of two between 0 and 1024. The second will be a string. The third, is a string selected from a list of three choices. And finally the fourth is a boolean option.

Edit config_schema.json with your favourite editor, adding the following: 

{
    "int_config":{
        "type":"int",
        "default":0,
        "label":"Int configuration",
        "description":"An example of an int configuration for OCCAM that must be defined between 0 and 1024, and must be a power of 2",
        "validations": [
            {
                "min": 0
            },
            {
                "max":1024
            },
            {
                "test": "log2(x) == floor(log2(x))",
                "message": "Must be a power of 2 between 0 and 1024"
            }
        ]
    },
    "string_config":{
        "type":"string",
        "default":"null",
        "description":"String configuration for OCCAM",
        "label":"Example of a string configuration"
    },
    "list_config":{
        "type":["default_option", "option_1", "option_2"],
        "default":"default_option",
        "description":"List configuration for OCCAM",
        "label":"Example of a list configuration"
    },
    "bool_config":{
        "type":"boolean",
        "default":false,
        "description":"An example of a bool configuration for OCCAM",
        "label":"Example of a bool configuration"
    }
}

Declaring the configuration schema in the object description file

Having the schema definition, we must add the corresponding declaration in the object description file (object.json): 

"configurations": [
    {
        "schema": "config_schema.json",
        "file": "input.json",
        "name": "Configuration Options"
    }
]

The new field "configurations" tells OCCAM that the definition of the configuration named Configuration Options is in the file config_schema.json, and that it should create the file input.json before running the object.

The object description file (object.json) should look like this: 

{
    "type": "simulator",
    "id": "95fdb476-8984-11e6-8e21-1c1b0d0a9044",
    "name": "ExampleSim",
    "configurations": [
        {
            "schema": "config_schema.json",
            "file": "input.json",
            "name": "Configuration Options"
        }
    ]
}

Commit the new revision

Now we can commit the new revision of the object. 

$ git add object.json
$ git add config_schema.json
$ git commit -am "New configuration options"
$ occam commit

Test the configuration options

At this point you can go into the OCCAM web page and test your object in an experiment. You will not be able to run it yet, but you can try to add the object to an experiment and see the result.

NEXT: Defining the Object Input

Updated