From da9898dc226bd0073e3c78913dd8947d4af3d3b8 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 14:44:46 +1000
Subject: [PATCH 01/16] Fix "pstring" docs subsection header to include mention
 of "encoding"

---
 doc/datatypes/utils.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index c64a3aa..7292903 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -109,7 +109,7 @@ or
 Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer.
 
 
-### **pstring** ({ countType: Type, ?count: Countable })
+### **pstring** ({ countType: Type, ?count: Countable, ?encoding: string })
 Arguments:
 * countType : the type of the length prefix
 * count : optional (either count or countType), a reference to the field counting the elements, or a fixed size (an integer)

From 5a390911ddc51b448f27fb77be1376bdfcf0426f Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 15:27:52 +1000
Subject: [PATCH 02/16] Fix "utils" markdown document to specify JSON as
 language of example JSON code-block - modifies language used to indicate what
 the numerals are

---
 doc/datatypes/utils.md | 8 +++++---
 1 file changed, 5 insertions(+), 3 deletions(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 7292903..511df1e 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -92,20 +92,22 @@ Example:
 ```
 
 or 
-```yaml
+```json
 [
   "bitflags",
   {
     "type": "lu32",
     "big": true,
     "flags": {
-      "onGround": 0b1,
-      "inAir": 0b10
+      "onGround": 1,
+      "inAir": 2
     }
   }
 ]
 ```
 
+where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`.
+
 Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer.
 
 

From 85b611b134dd1a350814b9e5a48d8bb46a10eb85 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 15:41:39 +1000
Subject: [PATCH 03/16] Fix spacing on "pstring"'s "encoding" argument to
 conform to existing format

---
 doc/datatypes/utils.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 511df1e..361a52e 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -115,7 +115,7 @@ Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": f
 Arguments:
 * countType : the type of the length prefix
 * count : optional (either count or countType), a reference to the field counting the elements, or a fixed size (an integer)
-* encoding: the encoding of the string, UTF-8 by default
+* encoding : the encoding of the string, UTF-8 by default
 
 Represents a string.
 

From 432d3cbdf9fc0c1bf21145e05947d5d85be4e73d Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:19:00 +1000
Subject: [PATCH 04/16] Fix 'langauge' typo

---
 doc/datatypes/utils.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 361a52e..51c7cc4 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -74,7 +74,7 @@ Example of value: `"int"`
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.
-* big : 64+ bits. In langauges like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
+* big : 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
 * shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask.
 
 Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types.

From c050dcbe0c869b3fd15ed0efe0673c216cfd6a6c Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:20:43 +1000
Subject: [PATCH 05/16] Fix optionality qualifier at beginning of word in
 subsection header

---
 doc/datatypes/utils.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 51c7cc4..ed5dd2f 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -70,7 +70,7 @@ Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```
 Example of value: `"int"`
 
-### **bitflags** ([ { type: string, flags: object | array, big?: boolean, shift?: number } ])
+### **bitflags** ([ { type: string, flags: object | array, ?big: boolean, ?shift: number } ])
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.

From 50e58ee94c83d57d372ee8348b4935766aae23f4 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:25:07 +1000
Subject: [PATCH 06/16] Fix primitives doc "cstring" subsection header to
 include its arguments

---
 doc/datatypes/primitives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md
index ddea505..3ec794e 100644
--- a/doc/datatypes/primitives.md
+++ b/doc/datatypes/primitives.md
@@ -7,7 +7,7 @@ Represents a boolean, encoded in one byte.
 
 Example of value: `true` / `false`
 
-### **cstring** ( )
+### **cstring** ({ ?encoding: String })
 Arguments: encoding
 
 Represents a null terminated string. Similar to strings in C.

From ec8d8402acfd85e5b78014b8a88f91662cd92130 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:27:33 +1000
Subject: [PATCH 07/16] Fix consistency on docs' subsection headers for types
 with no arguments

---
 doc/datatypes/numeric.md    | 2 +-
 doc/datatypes/primitives.md | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/datatypes/numeric.md b/doc/datatypes/numeric.md
index 9183861..46b6723 100644
--- a/doc/datatypes/numeric.md
+++ b/doc/datatypes/numeric.md
@@ -36,7 +36,7 @@ Example:
 ```
 Example of value: `65535` (size = 2) / `16777215` (size = 3)
 
-### **varint** ( )
+### **varint** ()
 Arguments: None
 
 [Protobuf](https://developers.google.com/protocol-buffers/docs/encoding#varints)-compatible representation for variable-length integers using one or more bytes. Intended for 32-bit unsigned integers, or signed 32-bit integers that have been directly cast to an integer (where the MSB is the sign bit) before encoding.
diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md
index 3ec794e..92ed71e 100644
--- a/doc/datatypes/primitives.md
+++ b/doc/datatypes/primitives.md
@@ -1,6 +1,6 @@
 ## Primitives
 
-### **bool** ( )
+### **bool** ()
 Arguments: None
 
 Represents a boolean, encoded in one byte.
@@ -23,7 +23,7 @@ Example: A string length prefixed by a varint.
 
 Example of value: `"my string"`
 
-### **void** ( )
+### **void** ()
 Arguments: None
 
 Represents an empty value.

From e6eb764bfd224470e4be1c09597c28d9b6091510 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:36:30 +1000
Subject: [PATCH 08/16] Fix consistency on how types are printed in subsection
 headers

---
 doc/datatypes/structures.md | 2 +-
 doc/datatypes/utils.md      | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/doc/datatypes/structures.md b/doc/datatypes/structures.md
index 6beaefd..a64954b 100644
--- a/doc/datatypes/structures.md
+++ b/doc/datatypes/structures.md
@@ -20,7 +20,7 @@ Example: An array of int prefixed by a short length.
 ```
 Example of value: `[1, 2, 3, 4]` (type = [i8](./numeric.md)) / `["ac", "dc"]` (type = [cstring](./utils.md))
 
-### **container** ([ { name: String, type: Type, ?anon: Bool }, ... ])
+### **container** ([ { name: String, type: Type, ?anon: Boolean }, ... ])
 Arguments: 
 * [array] : a field
 * * name : the name of field
diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index ed5dd2f..933a0fe 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -70,7 +70,7 @@ Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```
 Example of value: `"int"`
 
-### **bitflags** ([ { type: string, flags: object | array, ?big: boolean, ?shift: number } ])
+### **bitflags** ([ { type: String, flags: Object | Array, ?big: Boolean, ?shift: Number } ])
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.
@@ -111,7 +111,7 @@ where `1` and `2` respectively are the JSON-compatible, decimal representations
 Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer.
 
 
-### **pstring** ({ countType: Type, ?count: Countable, ?encoding: string })
+### **pstring** ({ countType: Type, ?count: Countable, ?encoding: String })
 Arguments:
 * countType : the type of the length prefix
 * count : optional (either count or countType), a reference to the field counting the elements, or a fixed size (an integer)

From 920e4cf2f94051737d694987a7af2aa1155e9d78 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:38:02 +1000
Subject: [PATCH 09/16] Fix "cstring" example correctly describes what it is

---
 doc/datatypes/primitives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md
index 92ed71e..0bd5c29 100644
--- a/doc/datatypes/primitives.md
+++ b/doc/datatypes/primitives.md
@@ -14,7 +14,7 @@ Represents a null terminated string. Similar to strings in C.
 Assumes UTF-8 encoding by default
 
 Example:
-Example: A string length prefixed by a varint.
+A UTF-16 string of unknown size that is expected to end with the zero character (null-terminal).
 ```json
 [
   "cstring", { "encoding": "utf-16" }

From 995c62538407ebfc8dc675a3223f70a8d89a0f45 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:38:47 +1000
Subject: [PATCH 10/16] Fix null-termination grammar

---
 doc/datatypes/primitives.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md
index 0bd5c29..b5e6878 100644
--- a/doc/datatypes/primitives.md
+++ b/doc/datatypes/primitives.md
@@ -10,7 +10,7 @@ Example of value: `true` / `false`
 ### **cstring** ({ ?encoding: String })
 Arguments: encoding
 
-Represents a null terminated string. Similar to strings in C.
+Represents a null-terminated string. Similar to strings in C.
 Assumes UTF-8 encoding by default
 
 Example:

From 7958660670fd25ab7047f7de8fb2e5ef87b3eb92 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:40:00 +1000
Subject: [PATCH 11/16] Fix "cstring" subsection "Arguments" list conforms to
 how other arguments are presented

---
 doc/datatypes/primitives.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/datatypes/primitives.md b/doc/datatypes/primitives.md
index b5e6878..790c9eb 100644
--- a/doc/datatypes/primitives.md
+++ b/doc/datatypes/primitives.md
@@ -8,10 +8,10 @@ Represents a boolean, encoded in one byte.
 Example of value: `true` / `false`
 
 ### **cstring** ({ ?encoding: String })
-Arguments: encoding
+Arguments:
+* encoding : the encoding of the string, UTF-8 by default
 
 Represents a null-terminated string. Similar to strings in C.
-Assumes UTF-8 encoding by default
 
 Example:
 A UTF-16 string of unknown size that is expected to end with the zero character (null-terminal).

From a8a138dca619f3f9a2a6ea6264eb1ea760594bbf Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 19:41:45 +1000
Subject: [PATCH 12/16] Fix "Example" subsubsection header appends newline
 consistently

---
 doc/datatypes/conditional.md | 4 ++--
 doc/datatypes/structures.md  | 9 ++++++---
 doc/datatypes/utils.md       | 9 ++++-----
 3 files changed, 12 insertions(+), 10 deletions(-)

diff --git a/doc/datatypes/conditional.md b/doc/datatypes/conditional.md
index 4526c45..79249f7 100644
--- a/doc/datatypes/conditional.md
+++ b/doc/datatypes/conditional.md
@@ -15,7 +15,6 @@ For `compareTo` variables, to go up one level when referencing a field, use "../
 Switch statement field names starting with "/" will reference a root variable. Root variables are primitives that can be used for comparisons and changed dynamically.
 
 Example:
-
 A switch which can encode a byte, a varint, a float or a string depending on "someField". 
 If the value of someField is different, then the value encoded is of type void.
 ```json
@@ -43,7 +42,8 @@ Represents a simple optional type.
 It's encoded as a boolean indicating whether the value is there or not.
 It's similar to the `Optional` type in java or `Maybe` in haskell.
 
-Example: An option of value string
+Example:
+An option of value string
 ```json
 [
   "option",
diff --git a/doc/datatypes/structures.md b/doc/datatypes/structures.md
index a64954b..a55a713 100644
--- a/doc/datatypes/structures.md
+++ b/doc/datatypes/structures.md
@@ -8,7 +8,8 @@ Arguments:
 
 Represents a list of values with same type.
 
-Example: An array of int prefixed by a short length.
+Example:
+An array of int prefixed by a short length.
 ```json
 [
   "array",
@@ -29,7 +30,8 @@ Arguments:
 
 Represents a list of named values.
 
-Example: A container with fields of type int, int, ushort and ushort.
+Example:
+A container with fields of type int, int, ushort and ushort.
 ```json
 [
   "container",
@@ -57,7 +59,8 @@ Arguments:
 
 Represents a count field for an array or a buffer. 
 
-Example: A count for a field name records, of type short.
+Example:
+A count for a field name records, of type short.
 ```json
 [
   "count",
diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 933a0fe..bd44d77 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -8,7 +8,8 @@ Arguments:
 
 Represents a raw bytes with count prefix/field or without it.
 
-Example: An buffer prefixed by a varint length.
+Example:
+An buffer prefixed by a varint length.
 ```json
 [
     "buffer",
@@ -29,7 +30,6 @@ Represents a list of value with sizes that are not a multiple of 8bits.
 The sum of the sizes must be a multiple of 8.
 
 Example:
-
 3 values, x, y and z with sizes in bits : 26, 12, 26. Notice that 26+12+26=64.
 ```json
 [
@@ -52,7 +52,6 @@ Arguments:
 Maps string to a values.
 
 Example:
-
 Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```json
 [
@@ -80,7 +79,6 @@ Arguments:
 Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types.
 
 Example:
-
 ```json
 [
   "bitflags",
@@ -119,7 +117,8 @@ Arguments:
 
 Represents a string.
 
-Example: A string length prefixed by a varint.
+Example:
+A string length prefixed by a varint.
 ```json
 [
   "pstring", { "countType": "varint", "encoding": "utf-8" }

From e5a56464927511ae9e8754641e8c9d19bde6114e Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 20:12:38 +1000
Subject: [PATCH 13/16] Fix "big" argument of "bitflags" type documentation to
 specify what the condition is

---
 doc/datatypes/utils.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index bd44d77..3a8a400 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -73,7 +73,7 @@ Example of value: `"int"`
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.
-* big : 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
+* big : If the type is 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
 * shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask.
 
 Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types.

From bac5e949075e4050a895689a58cc53b6320ce4c9 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 20:05:08 +1000
Subject: [PATCH 14/16] Fix "bitflags" shift argument is specified as boolean

---
 doc/datatypes/utils.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 3a8a400..6995bab 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -69,12 +69,12 @@ Maps a byte to a string, 1 to "byte", 2 to "short", 3 to "int", 4 to "long".
 ```
 Example of value: `"int"`
 
-### **bitflags** ([ { type: String, flags: Object | Array, ?big: Boolean, ?shift: Number } ])
+### **bitflags** ([ { type: String, flags: Object | Array, ?big: Boolean, ?shift: Boolean } ])
 Arguments:
 * type : The underlying integer type (eg varint, lu32).
 * flags : Either an array of flag values from LSB to MSB, or an object containing a mappng of valueName => bitMask.
 * big : If the type is 64+ bits. In languages like javascript (where all numbers are 64-bit floating points), special data types may have to be used for integers greater than 32 bits, so this must be set to true if the `type` is using the special data type.
-* shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask.
+* shift : Specify if flags is an object and holds bit positions as values opposed to a bitmask, false by default.
 
 Represents boolean flags packed into an integer. Similar to bitfields, but only intended for enumerated boolean flags (each flag occupies 1 bit), and supports arbitrary underlying integer types.
 

From b9737042572259b4ecbfadb743a5a2d35b48300f Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Thu, 30 Apr 2026 20:09:25 +1000
Subject: [PATCH 15/16] Add example for "shift" argument in "bitflags"
 subheader

---
 doc/datatypes/utils.md | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/doc/datatypes/utils.md b/doc/datatypes/utils.md
index 6995bab..b7a950c 100644
--- a/doc/datatypes/utils.md
+++ b/doc/datatypes/utils.md
@@ -104,7 +104,23 @@ or
 ]
 ```
 
-where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`.
+(where `1` and `2` respectively are the JSON-compatible, decimal representations of the bitmasks `0b01` and `0b10`)
+
+or 
+```json
+[
+  "bitflags",
+  {
+    "type": "lu32",
+    "big": true,
+    "shift": true,
+    "flags": {
+      "onGround": 0,
+      "inAir": 1
+    }
+  }
+]
+```
 
 Example of value to pass when writing: `{"flags": { "onGround": true, "inAir": false } }`. Likewise when reading you will get a similar object back, with a extra `_value` field holding the raw integer.
 

From ca84e5e45b3b86433fbc8636080e3a88c00ff693 Mon Sep 17 00:00:00 2001
From: MnPX <i@mnpx.dev>
Date: Fri, 1 May 2026 00:05:34 +1000
Subject: [PATCH 16/16] Update bitflags now has more specific schema specified
 - "flags" property's "object" alternative is overly permissive

---
 schemas/utils.json | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/schemas/utils.json b/schemas/utils.json
index c9d48b5..ec8a5b5 100644
--- a/schemas/utils.json
+++ b/schemas/utils.json
@@ -111,6 +111,32 @@
       },
       {
         "type": "object",
+        "properties": {
+          "type": "string",
+          "flags": {
+            "oneOf": [
+              {
+                "type": "object"
+              },
+              {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            ]
+          },
+          "big": {
+            "type": "boolean"
+          },
+          "shift": {
+            "type": "boolean"
+          }
+        },
+        "required": [
+          "type",
+          "flags"
+        ],
         "additionalItems": false
       }
     ],