# Schema Format

_**Supported syntaxes: JSON, XML, YAML**_

The following description uses the JSON syntax

For examples in different formats, see [example1.yaml](example1.yaml), [example2.yaml](example2.yaml), [example3.json](example3.json) and [example4.xml](example4.xml).

## Main layout

A schema contains a dictionary of structures. There must be at least one defined structure named "main" 
```json
{
  "structures": {
    "main": {
      ...
    },
    "struct1": {
      ...
    },
    "struct2": {
      ...
    },
    ...
  }
}
```

## Structure

A structure has a given number of bits and one or multiple ranges. Each range of bits can have a name, a description and / or values with special meaning (see [Range](#range)). A range's structure can also depend on another range's value (see [Dependencies](#dependencies))

The range name (or key) defines the left- and rightmost bits (e.g. 7-4 goes from bit 7 to bit 4). Bits are displayed in big-endian, i.e. the leftmost bit has the highest value.
```json
"main": {
  "bits": 8,
  "ranges": {
    "7-4": {
      ...
    },
    "3-2": {
      ...
    },
    "1": {
      ...
    },
    "0": {
      ...
    }
  }
}
```

## Range

A range represents a group of consecutive bits. It can have a name (display in the bit cells), a description (displayed under the structure) and / or values.

For values depending on other ranges, see [Dependencies](#dependencies).

> **Note**<br>
> In YAML, make sure to wrap values in quotes because some values can be interpreted as octal notation (e.g. 010)

```json
"3-2": {
  "name": "op",
  "description": "Logical operation",
  "values": {
    "00": "AND",
    "01": "OR",
    "10": "XOR",
    "11": "NAND"
  }
}
```

## Dependencies

The structure of one range may depend on the value of another. To represent this situation, first indicate on the child range the range on which it depends:

```json
"7-4": {
  ...
  "depends-on": "0"
}
```

Then, in its values, indicate which structure to use. A description can also be added (displayed above the horizontal dependency arrow)

```json
"7-4": {
  ...
  "depends-on": "0",
  "values": {
    "0": {
      "description": "immediate value",
      "structure": "immediateValue"
    },
    "1": {
      "description": "value in register",
      "structure": "registerValue"
    }
  }
}
```

Finally, add the sub-structures to the structure dictionary:

```json
{
  "structures": {
    "main": {
      ...
    },
    "immediateValue": {
      "bits": 4,
      ...
    },
    "registerValue": {
      "bits": 4,
      ...
    },
    ...
  }
}
```