Schema commands (KEKS)

Schema commands ¶

Data structure validation commands are grouped in so-called map of schemas. Map’s key is schema name. Schema’s value is a list of commands. Each command is a list of string-encoded words (with several exceptions). First element of the command’s list is a command name. Possible following elements are command-specific.

Here is full list of structure validation commands, that should be generated from higher level schema descriptions.

name	encoded	args	description
TAKE	`.`	k	Take/choose the value of the `k` key in the map, if `k` is a string. If `k` is integer, then choose the k-th value in a list. If `k` equals to `.`, then choose the element you are currently in. Command never fails, but key can be non-existent.
EXISTS	`E`		Assure that chosen element exists.
!EXISTS	`!E`		Assure that chosen element does not exist.
EACH	`*`		Execute the next command against every element of the chosen (if it exists) list, or every value of the map.
TYPE	`T`	T0 [T1 ...]	Check that chosen (if it exists) element’s type is in (T0, T1 ...) set. Possible types: BIN, BLOB, BOOL, HEXLET, INT, LIST, MAGIC, MAP, NIL, STR, TAI.
GT	`>`	n	Check that chosen (if it exists) integer value is greater than `n`. If chosen value is either list or map, then check their length. If the value is a string, then check its length.
LT	`<`	n	Same as `>`, but check that value is less than `n`.
SCHEMA	`S`	s	Check chosen (if it exists) element against schema named `s`.
TIMEPREC	`TP`	p	Check that chosen (if it exists) element, of time type, has value of maximal specified time precision. `p` is integer with following possible values: 0 – only full seconds allowed, no parts; 3 – only up to milliseconds; 6 – only up to microseconds; 9 – only up to nanoseconds; 12 – only up to picoseconds; 15 – only up to femtoseconds; 18 – up to attoseconds;
UTC	`UTC`		Check that chosen (if it exists) element, of time type, can be converted to UTC.
EQ	`=`	v	Check that chosen (if it exists) element’s value equals to binary string `v`.

For example let’s check "our" structure, described in CDDL as:

ai = text .gt 0
fpr = bytes .size 32
our = {a: ai, v: bytes/text, fpr: fpr, ?comment: text}

a, v, fpr fields are required ones. v has two allowable types. comment is optional, but typed. And fpr has fixed length. Corresponding schema can be:

{"our": [
    [".", "a"],
    ["E"],
    [".", "a"],
    ["T", "STR"],
    [".", "a"],
    [">", 0],

    [".", "v"],
    ["E"],
    [".", "v"],
    ["T", "BIN", "STR"],

    [".", "fpr"],
    ["E"],
    [".", "fpr"],
    ["T", "BIN"],
    [".", "fpr"],
    [">", 31],
    [".", "fpr"],
    ["<", 33],

    [".", "comment"],
    ["T", "STR"],
]}

Here is example with multiple schemas:

latitude = -90..90
longitude = -180..180
where = [latitude, longitude]
wheres = [+ where]

{
    "where": [
        [".", "."],
        ["T", "LIST"],
        [".", "."],
        [">", 1],
        [".", "."],
        ["<", 3],
        [".", "."],
        ["*"],
        [".", "INT"],
        [".", 0],
        [">", -91],
        [".", 0],
        ["<", 91],
        [".", 1],
        [">", -181],
        [".", 1],
        ["<", 181],
    ],
    "wheres": [
        [".", "."],
        ["T", "LIST"],
        [".", "."],
        [">", 0],
        [".", "."],
        ["*"],
        ["S", "where"],
    ],
}