docs: naming rules for Named Structs

site/docs/types/_config

@@ -3,3 +3,4 @@ arrange:
   - type_classes.md
   - type_variations.md
   - type_parsing.md
+  - named_structs.md

site/docs/types/named_structs.md

@@ -0,0 +1,83 @@
+# Named Structs
+
+A Named Struct is a special type construct that combines:
+* A Struct type
+* A list of names for the fields in the Struct, in depth-first search order
+
+The depth-first search order for names arises from the the ability to nest Structs within other types. All struct fields must be named, even nested fields.
+
+Named Structs are most commonly used to model the schema of Read relations.
+
+> Note: In this page Structs are annotated with names for readabilty.
+> In practice Structs to not contain name information.
+
+## Determining Names
+When producing/consuming names for a NamedStruct, some types require special handling:
+
+### Struct
+A struct has names for each of its inner fields.
+
+For example, the following Struct
+```
+struct<a: i64, b: i64>
+```
+has 2 names, one for each of its inner fields.
+
+### Structs within Compound Types
+Struct types nested in compound types must also be be named.
+
+#### Structs within Maps
+If a Map contains Structs, either as keys or values or both, the Struct fields must be named. Keys are named before values. For example the following Map
+```
+map<struct<a: i64, b: i64>, c: struct<d: i64, e: i64, f: i64>>
+```
+has 5 named fields
+* 2 names [a, b] for the struct fields used as a key
+* 3 names [c, d, e] for the struct fields used as a value
+
+#### Structs within List
+If a List contains Structs, the Struct fields must be named. For example the following List
+```
+list<struct<a: i64, b: i64>>
+```
+has 2 named fields [a, b] for the struct fields.
+
+#### Structs within Struct
+Structs can also be embedded within Structs.
+
+A Struct like
+```
+struct<a: struct<b: i64, c: i64>, d: struct<e: i64, f: i64, g: i64>>
+```
+has 7 names
+* 1 name [a] for the 1st nested struct field
+* 2 names [b, c] for the fields within the 1st nested struct
+* 1 name [d] the for the 2nd nested struct field
+* 3 names [e, f, g] for the fields within the 2nd nested struct
+
+### Putting It All Together
+
+#### Simple Named Struct
+```
+NamedStruct {
+    names: [a, b, c, d]
+    struct: struct<a: i64, b: list<i64>, c: map<i64, i64>, d: i64>
+}
+```
+
+#### Structs in Compound Types
+```
+NamedStruct {
+    names: [a, b, c, d, e, f, g, h]
+    struct: struct<a: i64, b: list<struct<c: i64, d: i64>>, e: map<i64, struct<f: i64, g: i64>>, h:i64>
+}
+```
+
+#### Structs in Structs
+```
+NamedStruct {
+    names: [a, b, c, d, e, f, g, h, i]
+    struct: struct<a: i64, b: struct<c: i64, d: struct<e: i64, f: i64>, g: i64, h: struct<i: i64, j: i64>>>>
+}
+```
+