PR FIXUP - Expand documentation on local vs global fields

client/collection_description.go

@@ -60,7 +60,11 @@ type CollectionDescription struct {
 	// - [CollectionSource]
 	Sources []any
 
-	// Fields contains the fields within this Collection.
+	// Fields contains the fields local to the node within this Collection.
+	//
+	// Most fields defined here will also be present on the [SchemaDescription]. A notable
+	// exception to this are the fields of the (optional) secondary side of a relation
+	// which are local only, and will not be present on the [SchemaDescription].
 	Fields []CollectionFieldDescription
 
 	// Indexes contains the secondary indexes that this Collection has.

client/schema_description.go

@@ -31,7 +31,14 @@ type SchemaDescription struct {
 	// It is immutable.
 	Name string
 
-	// Fields contains the fields within this Schema.
+	// Fields contains the fields globally defined across the node network within this Schema.
+	//
+	// Any [CollectionDescription]s that reference this [SchemaDescription] will have a field
+	// set that contains all of these fields, plus any local only fields (such as the secondary side
+	// of a relation).
+	//
+	// Embedded objects (including within Views) are schema-only, and as such fields of embedded
+	// objects will not have a corresponding [CollectionFieldDescription].
 	//
 	// Currently new fields may be added after initial declaration, but they cannot be removed.
 	Fields []SchemaFieldDescription