added README.md + format.md

format.md

@@ -0,0 +1,125 @@
+# 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,
+      ...
+    },
+    ...
+  }
+}
+```