[typespec-go] Always document raw JSON fields emitted as []byte

.chronus/changes/typespec-go-rawjson-doc-comment-2026-07-28-05-40-00.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-go"
+---
+
+Always document raw JSON fields (emitted as `[]byte`) so callers know to marshal their data structure into the bytes.

packages/typespec-go/src/codegen/core/models.ts

@@ -269,12 +269,18 @@ function generateModelDefs(
           field.docs.description = "";
         }
         field.docs.description += `Field has constant value ${helpers.formatLiteralValue(field.type, false)}, any specified value is ignored.`;
+      } else if (field.type.kind === "rawJSON") {
+        // raw JSON is emitted as []byte, so document that the field contains raw
+        // JSON and that the caller is responsible for marshaling their data structure.
+        if (field.docs.description) {
+          field.docs.description += "\n";
+        } else {
+          field.docs.description = "";
+        }
+        field.docs.description += "The contents of this field are raw JSON.";
       }
       if (field.docs.description) {
         descriptionMods.push(field.docs.description);
-      } else if (field.type.kind === "rawJSON") {
-        // add a basic description if one isn't available
-        descriptionMods.push("The contents of this field are raw JSON.");
       }
       field.docs.description = descriptionMods.join("; ");
     }

packages/typespec-go/test/unittest/scenarios/rawjson-as-bytes.md

@@ -9,6 +9,9 @@ namespace RawJson;
 model ContainsRawJson {
   anything1: unknown;
   anything2: unknown;
+
+  @doc("Additional properties supplied by the caller.")
+  extras?: unknown;
 }
 
 @put
@@ -37,5 +40,9 @@ type ContainsRawJSON struct {
 
 	// REQUIRED; The contents of this field are raw JSON.
 	Anything2 []byte
+
+	// Additional properties supplied by the caller.
+	// The contents of this field are raw JSON.
+	Extras []byte
 }
 ```