Schemas

A schema describes the acceptable values for a parameter. It is written in JSON and inspired by JSON schema. In addition, the schema describes the form that will be displayed when adding or editing a setting associating a value to target variable.

Basic Types

By default, when creating a parameter with ComodIT’s web interface (see this example), you have to choose between 4 base types:

String: any string,
Boolean: a boolean (true or false),
Integer: any integer number,
Number: any real number.

These types are in fact represented by a very simple schema containing the single field type, for example:

{"type":"string"}

Advanced Types

Type field may have one of the following values:

string
boolean
integer
number
array
object

The first 4 values are associated to above base types. ‘array’ type describes a list of values and ‘object’ type is used to represent a key-value map.

The value of ‘type’ field might require additional fields. With ‘array’ type, an additional ‘items’ field is required. The value of this field is another schema describing acceptable values for the items of the array. For example, a parameter whose value must be an array of integers has the following schema:

{
    "type": "array",
    "items": {
        "type": "integer"
    }
}

An acceptable value is then [1, 2, 3].

‘object’ type requires field ‘properties’ which describes the fields of the object. The value of this field is a map whose keys are field names and values schemas describing acceptable values of the object’s fields. For instance, a parameter whose value must be an object with 3 fields a, b and c whose values are respectively an integer, a boolean and a string has the following schema:

{
    "type": "object",
    "properties": {
        "a": {
            "type": "integer"
        },
        "b": {
            "type": "boolean"
        },
        "c": {
            "type": "string"
        }
    }
}

An acceptable value is then {"a": 1, "b": true, "c": "hello"}.

Optional fields

Optional additional fields may be used in a schema. These have 2 main purposes: enforce additional constraints on value or impact presentation in UI. Constraints are both verified client and server side. Note that constraints may also impact UI.

Constraints

‘min’ and ‘max’: are used to define the minimum and the maximum of an integer or a number.
‘required’: implies that the field associated to this value in the UI cannot be empty on form validation. This field will be marked with a red star in the UI.
‘enum’: an array defining the possible values of a string. A list box will be displayed in the UI instead of a text box. Note that if the field is not required as well, the empty string is automatically added to list box.

UI only

‘pretty’: for an object field, the text of the label of associated field in the UI.
‘description’: for an object field, the text of the tooltip of associated field in the UI.
‘default’: for an object’s field, the default value.
‘secret’: for a string, implies that stars (‘*’) are displayed instead of the characters in the UI.
‘index’: a boolean flag associated to an object’s field. If the object is in an array, the value of this field will be used in the UI to refer to this element instead of caption ‘Item #i’.

Example

The following schema describes the repositories that may be defined during the kickstart installation of a CentOS distribution. It is actually an array, each element (here, an object) representing a repository. Each repository is defined by a name, a base URL or a mirror list, and a flag indicating if a release package has to be installed.

{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "mirror_list": {
                "description": "Mirror list URL",
                "type": "string",
                "pretty": "Mirror List"
            },
            "name": {
                "description": "The name of the repository",
                "required": true,
                "type": "string",
                "pretty": "Name",
                "index": true
            },
            "release": {
                "default": false,
                "description": "If true, install package x-release where x is the name of the repository",
                "required": true,
                "type": "boolean",
                "pretty": "Release"
            },
            "base_url": {
                "description": "Repository base URL",
                "type": "string",
                "pretty": "Base URL"
            }
        }
    }
}

An acceptable value for above schema is as follows:

[{
    "mirror_list": "https://mirrors.fedoraproject.org/metalink?repo=epel-6&arch=x86_64",
    "name": "epel",
    "release": true
}, {
    "mirror_list": "http://mirrorlist.centos.org/?release=6&arch=x86_64&repo=updates",
    "name": "updates",
    "release": false
}, {
    "name": "comodit",
    "base_url": "http://dl.comodit.com/pub/centos/6/x86_64/",
    "release": true
}]

Finally, this value is displayed as shown in the following figure in the UI.

Left-side column allows to select a particular element of the array. Values of ‘name’ field are used to identify the elements thanks to ‘index’ flag. Values of ‘pretty’ fields are used the identify the fields in right-side panel. A red start implied by ‘required’ flag signals that field ‘name’ must be completed in order to validate value. Finally, when clicking on an ‘info’ icon, the text of ‘description’ field is displayed.

Schemas

Basic Types

Advanced Types

Optional fields

Constraints

UI only

Example

About

Stay Connected

Recent Blog Entries

Contact Us